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

RationalMaps -- rational maps between projective varieties
**********************************************************

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

RationalMaps is a package for computing things related to maps between
projective varieties.

It focuses on finding where a birational map is undefined, checking whether a
map is a closed embedding, checking birationality and computing inverse maps

Mathematical background:
  * A. V. Dória, S. H. Hassanzadeh, A. Simis,    A characteristic free
    criterion of birationality, Advances in Mathematics, Volume 230, Issue 1, 1
    May 2012, Pages 390-413.
  * A. Simis,   Cremona Transformations and some Related Algebras, Journal of
    Algebra, Volume 280, Issue 1, 1 October 2004, Pages 162--179
Functionality overlap with other packages:

Parametrization,:  While the package
Parametrization, focuses mostly on curves, it also
includes a function invertBirationalMap (Parametrization),
that has the same functionality as
inverseOfMap.  On the other hand, these two functions were
implemented differently and so sometimes one function can be substantially
faster than the other.

See Cremona,:  The package Cremona, focuses
on  fast probabilistic computations in general cases and  deterministic
computations for special kinds of maps from projective space.  More precisely,
  * isBirational (Cremona), gives a probabilistic answer to
    the question of whether a map between varieties is birational.
    Furthermore, if the source is projective space, then degreeOfRationalMap
    with MathMode=>true gives a deterministic correct answer. In some cases,
    the speed of the latter  is comparable with isBirationalMap,
    with AssumeDominant=>true.
  * inverseMap (Cremona), gives a  fast computation of the
    inverse of a birational map if the source is projective space  and the map
    has maximal linear rank.   In some cases, even if the map has maximal
    linear rank, our function inverseOfMap, appears to be
    competitive however.  If you pass inverseMap a map not from projective
    space, then it calls a modified and improved version of
    invertBirationalMap (Parametrization), from
    Parametrization.

Authors
=======

  * Karl Schwede (see http://www.math.utah.edu/~schwede ) <kschwede@gmail.com>
  * Daniel Smolkin (see http://dan.smolk.in ) <smolkind@umich.edu>
  * S. Hamid Hassanzadeh (see
    https://www.researchgate.net/profile/Seyed_Hassanzadeh )
    <hassanzadeh.ufrj@gmail.com>
  * C.J. Bott (see https://www.math.tamu.edu/directory/formalpg.php?user=cbott2
    ) <cjamesbott@gmail.com>

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

Version 1.0 of this package was accepted for publication in volume 12 (see
https://msp.org/jsag/2022/12-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 17 July 2022, in the article
RationalMaps, a package for Macaulay2 (see
https://msp.org/jsag/2022/12-1/p03.xhtml ) (DOI: 10.2140/jsag.2022.12.17 (see
https://doi.org/10.2140/jsag.2022.12.17 )). That version can be obtained from
the journal (see https://msp.org/jsag/2022/12-1/jsag-v12-n1-x03-RationalMaps.m2
).

Version
=======

This documentation describes version 1.0 of RationalMaps, released March 11th,
2022.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{RationalMapsSource,                                                    |
|  title = {{RationalMaps: rational maps between varieties. Version~1.0}},    |
|  author = {Karl Schwede and Daniel Smolkin and S. Hamid Hassanzadeh and C.J.|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{RationalMapsArticle,                                                |
|  title = {{RationalMaps, a package for \emph{Macaulay2}}},                  |
|  author = {Karl Schwede and Daniel Smolkin and S. Hamid Hassanzadeh and C.J.|
|  journal = {The Journal of Software for Algebra and Geometry},              |
|  volume = {12},                                                             |
|  year = {2022},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|Bott},                                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Bott},                                                                       |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * RationalMapping -- a rational mapping between
        projective varieties
  * Functions and commands
      * baseLocusOfMap -- the base locus of a map from a
        projective variety to projective space
      * idealOfImageOfMap -- finds defining equations
        for the image of a rational map between varieties or schemes
      * inverseOfMap -- inverse of a birational map
        between projective varieties
      * isBirationalMap -- whether a map between
        projective varieties is birational
      * isBirationalOntoImage -- whether a map
        between projective varieties is birational onto its image
      * isEmbedding -- whether a rational map of projective
        varieties is a closed embedding
      * isRegularMap -- whether a map to projective space
        is regular
      * isSameMap -- whether two rational maps to between
        projective varieties are really the same
      * jacobianDualMatrix -- computes the Jacobian
        dual matrix
      * mapOntoImage -- the induced map from a variety to
        the closure of its image under a rational map
      * "rationalMapping" -- see RationalMapping, -- a
        rational mapping between projective varieties
      * sourceInversionFactor -- computes the
        common factor among the components of the composition of the inverse
        map and the original map
  * Methods
      * "baseLocusOfMap(RationalMapping)" -- see baseLocusOfMap,
        -- the base locus of a map from a projective variety to
        projective space
      * "baseLocusOfMap(RingMap)" -- see baseLocusOfMap,
        -- the base locus of a map from a projective variety to projective
        space
      * "idealOfImageOfMap(RationalMapping)" -- see idealOfImageOfMap,
        -- finds defining equations for the image of a
        rational map between varieties or schemes
      * "idealOfImageOfMap(RingMap)" -- see idealOfImageOfMap,
        -- finds defining equations for the image of a
        rational map between varieties or schemes
      * "inverseOfMap(RationalMapping)" -- see inverseOfMap,
        -- inverse of a birational map between projective
        varieties
      * "inverseOfMap(RingMap)" -- see inverseOfMap, --
        inverse of a birational map between projective varieties
      * "isBirationalMap(RationalMapping)" -- see isBirationalMap,
        -- whether a map between projective varieties is
        birational
      * "isBirationalMap(RingMap)" -- see isBirationalMap,
        -- whether a map between projective varieties is
        birational
      * "isBirationalOntoImage(RationalMapping)" -- see
        isBirationalOntoImage, -- whether a map between
        projective varieties is birational onto its image
      * "isBirationalOntoImage(RingMap)" -- see isBirationalOntoImage,
        -- whether a map between projective varieties is
        birational onto its image
      * "isEmbedding(RationalMapping)" -- see isEmbedding,
        -- whether a rational map of projective varieties is a closed embedding
      * "isEmbedding(RingMap)" -- see isEmbedding, --
        whether a rational map of projective varieties is a closed embedding
      * "isRegularMap(RationalMapping)" -- see isRegularMap,
        -- whether a map to projective space is regular
      * "isRegularMap(RingMap)" -- see isRegularMap, --
        whether a map to projective space is regular
      * "isSameMap(RationalMapping,RationalMapping)" -- see isSameMap,
        -- whether two rational maps to between projective varieties
        are really the same
      * "isSameMap(RingMap,RingMap)" -- see isSameMap, --
        whether two rational maps to between projective varieties are really
        the same
      * "RationalMapping == RationalMapping" -- see isSameMap,
        -- whether two rational maps to between projective varieties are really
        the same
      * "jacobianDualMatrix(RationalMapping)" -- see jacobianDualMatrix,
        -- computes the Jacobian dual matrix
      * "jacobianDualMatrix(RingMap)" -- see jacobianDualMatrix,
        -- computes the Jacobian dual matrix
      * map(RationalMapping) -- the ring map
        associated to a RationalMapping between projective varieties
      * "mapOntoImage(RationalMapping)" -- see mapOntoImage,
        -- the induced map from a variety to the closure of its
        image under a rational map
      * "mapOntoImage(RingMap)" -- see mapOntoImage, -- the
        induced map from a variety to the closure of its image under a rational
        map
      * net(RationalMapping) (missing documentation)
      * "rationalMapping(ProjectiveVariety,ProjectiveVariety,BasicList)" -- see
        RationalMapping, -- a rational mapping between
        projective varieties
      * "rationalMapping(ProjectiveVariety,ProjectiveVariety,Matrix)" -- see
        RationalMapping, -- a rational mapping between
        projective varieties
      * "rationalMapping(Ring,Ring,BasicList)" -- see RationalMapping,
        -- a rational mapping between projective varieties
      * "rationalMapping(Ring,Ring,Matrix)" -- see RationalMapping,
        -- a rational mapping between projective varieties
      * "rationalMapping(RingMap)" -- see RationalMapping,
        -- a rational mapping between projective varieties
      * RationalMapping * RationalMapping
        -- compose rational maps between projective varieties
      * "RationalMapping ^ ZZ" -- see RationalMapping * RationalMapping,
        -- compose rational maps between
        projective varieties
      * source(RationalMapping) -- returns
        the source or target of a RationalMapping between projective varieties.
      * "target(RationalMapping)" -- see source(RationalMapping),
        -- returns the source or target of a
        RationalMapping between projective varieties.
      * "sourceInversionFactor(RingMap)" -- see sourceInversionFactor,
        -- computes the common factor among the
        components of the composition of the inverse map and the original map
  * Symbols
      * AssumeDominant -- whether to assume a rational
        map between projective varieties is dominant
      * CheckBirational -- whether to check
        birationality
      * HybridLimit -- an option to control HybridStrategy
      * HybridStrategy -- A strategy for determining
        whether a map is birational and computing its inverse
      * MinorsLimit -- an option to limit the number of
        random minors computed
      * QuickRank --  an option for controlling how rank is
        computed
      * ReesStrategy -- a strategy for determining whether
        a map is birational and computing its inverse
      * SaturateOutput -- whether the value returned
        should be saturated
      * SaturationStrategy -- a strategy for
        determining whether a map is birational and computing its inverse
      * SimisStrategy -- a strategy for determining
        whether a map is birational and computing its inverse

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

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

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

The source of this document is in RationalMaps.m2:1382:0.

AssumeDominant -- whether to assume a rational map between projective varieties is dominant
*******************************************************************************************

  * Usage:
        AssumeDominant=>b

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

  If AssumeDominant is true, it can speed up computation as a kernel will not
be computed.

Functions with optional argument named AssumeDominant:
======================================================

  * "inverseOfMap(...,AssumeDominant=>...)" -- see inverseOfMap,
    -- inverse of a birational map between projective varieties
  * "isBirationalMap(...,AssumeDominant=>...)" -- see isBirationalMap,
    -- whether a map between projective varieties is
    birational
  * "isBirationalOntoImage(...,AssumeDominant=>...)" -- see
    isBirationalOntoImage, -- whether a map between
    projective varieties is birational onto its image
  * "isEmbedding(...,AssumeDominant=>...)" -- see isEmbedding,
    -- whether a rational map of projective varieties is a closed
    embedding
  * "jacobianDualMatrix(...,AssumeDominant=>...)" -- see
    jacobianDualMatrix, -- computes the Jacobian dual
    matrix
  * "sourceInversionFactor(...,AssumeDominant=>...)" -- see
    sourceInversionFactor, -- computes the common factor
    among the components of the composition of the inverse map and the original
    map

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

The object AssumeDominant, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1448:0.

baseLocusOfMap -- the base locus of a map from a projective variety to projective space
***************************************************************************************

  * Usage:
        I = baseLocusOfMap(h)
        I = baseLocusOfMap(phi)
  * Inputs:
      * h, a ring map (Macaulay2Doc), a ring map corresponding
        to a rational map of projective varieties
      * phi, an instance of the type RationalMapping, a
        rational map between projective varieties
  * Optional inputs (Macaulay2Doc),:
      * SaturateOutput => a Boolean value (Macaulay2Doc),
        default value true, if set to true then the output will be saturated
      * Verbosity => an integer (Macaulay2Doc), default value 0, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
  * Outputs:
      * I, an ideal (Macaulay2Doc), the saturated defining ideal
        of the base locus of the corresponding maps

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

This defines the locus where a given map of projective varieties is not
defined.  If the option SaturateOutput is set to false, the output will not be
saturated.  The default value is true.  Consider the following rational map
from $P^2$ to $P^1$.

+--------------------------+
|i1 : R = QQ[x,y,z];       |
+--------------------------+
|i2 : S = QQ[a,b];         |
+--------------------------+
|i3 : f = map(R, S, {x,y});|
|                          |
|o3 : RingMap R <-- S      |
+--------------------------+
|i4 : baseLocusOfMap(f)    |
|                          |
|o4 = ideal (y, x)         |
|                          |
|o4 : Ideal of R           |
+--------------------------+

Observe it is not defined at the point [0:0:1], which is exactly what one
expects.  However, we can restrict the map to a curve in $P^2$ and then it will
be defined everywhere.

+---------------------------------------+
|i5 : R=QQ[x,y,z]/(y^2*z-x*(x-z)*(x+z));|
+---------------------------------------+
|i6 : S=QQ[a,b];                        |
+---------------------------------------+
|i7 : f=rationalMapping(R,S,{x,y});     |
+---------------------------------------+
|i8 : baseLocusOfMap(f)                 |
|                                       |
|o8 = ideal 1                           |
|                                       |
|o8 : Ideal of R                        |
+---------------------------------------+

Let us next consider the quadratic Cremona transformation.

+------------------------------------------------+
|i9 : R=QQ[x,y,z];                               |
+------------------------------------------------+
|i10 : S=QQ[a,b,c];                              |
+------------------------------------------------+
|i11 : f=map(R,S,{y*z,x*z,x*y});                 |
|                                                |
|o11 : RingMap R <-- S                           |
+------------------------------------------------+
|i12 : J=baseLocusOfMap(f)                       |
|                                                |
|o12 = ideal (y*z, x*z, x*y)                     |
|                                                |
|o12 : Ideal of R                                |
+------------------------------------------------+
|i13 : minimalPrimes J                           |
|                                                |
|o13 = {ideal (y, x), ideal (z, x), ideal (z, y)}|
|                                                |
|o13 : List                                      |
+------------------------------------------------+

The base locus is exactly the three points one expects.

Ways to use baseLocusOfMap:
===========================

  * "baseLocusOfMap(RationalMapping)"
  * "baseLocusOfMap(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2075:0.

CheckBirational -- whether to check birationality
*************************************************

  * Usage:
        CheckBirational=>b

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

If true, inverseOfMap, isEmbedding and sourceInversionFactor  will check
whether the passed map is birational. If it is not birational, it will throw an
error.

See also
========

  * inverseOfMap -- inverse of a birational map between
    projective varieties
  * isEmbedding -- whether a rational map of projective
    varieties is a closed embedding
  * sourceInversionFactor -- computes the common
    factor among the components of the composition of the inverse map and the
    original map

Functions with optional argument named CheckBirational:
=======================================================

  * "inverseOfMap(...,CheckBirational=>...)" -- see inverseOfMap,
    -- inverse of a birational map between projective varieties
  * "sourceInversionFactor(...,CheckBirational=>...)" -- see
    sourceInversionFactor, -- computes the common factor
    among the components of the composition of the inverse map and the original
    map

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

The object CheckBirational, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1398:0.

HybridLimit -- an option to control HybridStrategy
**************************************************

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

This controls behavior when using Strategy=>HybridStrategy.  By increasing the
HybridLimit value (default 15), HybridStrategy will execute SimisStrategy
longer. Infinity will behave exactly like SimisStrategy.

See also
========

  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse

Functions with optional argument named HybridLimit:
===================================================

  * "inverseOfMap(...,HybridLimit=>...)" -- see inverseOfMap,
    -- inverse of a birational map between projective varieties
  * "isBirationalMap(...,HybridLimit=>...)" -- see isBirationalMap,
    -- whether a map between projective varieties is
    birational
  * "isBirationalOntoImage(...,HybridLimit=>...)" -- see
    isBirationalOntoImage, -- whether a map between
    projective varieties is birational onto its image
  * "isEmbedding(...,HybridLimit=>...)" -- see isEmbedding,
    -- whether a rational map of projective varieties is a closed embedding
  * "sourceInversionFactor(...,HybridLimit=>...)" -- see
    sourceInversionFactor, -- computes the common factor
    among the components of the composition of the inverse map and the original
    map

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

The object HybridLimit, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1410:0.

HybridStrategy -- A strategy for determining whether a map is birational and computing its inverse
**************************************************************************************************

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

HybridStrategy is a valid value for the Strategy Option for inverseOfMap,
isBirationalMap, and isEmbedding. This is currently the default strategy.  It
is a combination of ReesStrategy and SimisStrategy. Increasing the HybridLimit
value (default 15) will force SimisStrategy to be executed longer.

See also
========

  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * SaturationStrategy -- a strategy for determining
    whether a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * HybridLimit -- an option to control HybridStrategy

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

The object HybridStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1467:0.

idealOfImageOfMap -- finds defining equations for the image of a rational map between varieties or schemes
**********************************************************************************************************

  * Usage:
        im = idealOfImageOfMap(p)
        im = idealOfImageOfMap(phi)
  * Inputs:
      * p, a ring map (Macaulay2Doc), corresponding to a
        rational map of projective varieties
      * phi, an instance of the type RationalMapping, a
        rational map between projective varieties
  * Optional inputs (Macaulay2Doc),:
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
      * Verbosity => ..., default value 0
  * Outputs:
      * im, an ideal (Macaulay2Doc), defining equations for the
        image

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

Given a rational map $f : X \to Y \subset P^N$, idealOfImageOfMap returns the
defining ideal of the image of $f$ in $P^N$. The rings provided implicitly in
the inputs should be polynomial rings or quotients of polynomial rings. In
particular, idealOfImageOfMap function returns an ideal defining a subset of
the ambient projective space of the image.  In the following example we
consider the image of $P^1$ inside $P^1 \times P^1$.

+---------------------------------------------------+
|i1 : S = QQ[x,y,z,w];                              |
+---------------------------------------------------+
|i2 : b = ideal(x*y-z*w);                           |
|                                                   |
|o2 : Ideal of S                                    |
+---------------------------------------------------+
|i3 : R = QQ[u,v];                                  |
+---------------------------------------------------+
|i4 : a = ideal(sub(0,R));                          |
|                                                   |
|o4 : Ideal of R                                    |
+---------------------------------------------------+
|i5 : f = matrix {{u,0,v,0}};                       |
|                                                   |
|             1      4                              |
|o5 : Matrix R  <-- R                               |
+---------------------------------------------------+
|i6 : phi = rationalMapping(R/a, S/b, f)            |
|                                                   |
|                             S                     |
|o6 = Proj R - - - > Proj(---------)   {u, 0, v, 0} |
|                         x*y - z*w                 |
|                                                   |
|o6 : RationalMapping                               |
+---------------------------------------------------+
|i7 : idealOfImageOfMap(phi)                        |
|                                                   |
|o7 = ideal (w, y)                                  |
|                                                   |
|                  S                                |
|o7 : Ideal of ---------                            |
|              x*y - z*w                            |
+---------------------------------------------------+
|i8 : psi = rationalMapping(Proj(S/b), Proj(R/a), f)|
|                                                   |
|                             S                     |
|o8 = Proj R - - - > Proj(---------)   {u, 0, v, 0} |
|                         x*y - z*w                 |
|                                                   |
|o8 : RationalMapping                               |
+---------------------------------------------------+
|i9 : idealOfImageOfMap(psi)                        |
|                                                   |
|o9 = ideal (w, y)                                  |
|                                                   |
|                  S                                |
|o9 : Ideal of ---------                            |
|              x*y - z*w                            |
+---------------------------------------------------+

This function frequently just calls ker (Macaulay2Doc),
from Macaulay2.  However, if the target of
the ring map is a polynomial ring, then it first tries to verify whether the
ring map is injective.  This is done by computing the rank of an appropriate
Jacobian matrix.

Ways to use idealOfImageOfMap:
==============================

  * "idealOfImageOfMap(RationalMapping)"
  * "idealOfImageOfMap(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:1847:0.

inverseOfMap -- inverse of a birational map between projective varieties
************************************************************************

  * Usage:
        psi = inverseOfMap(g)
        psi = inverseOfMap(phi)
  * Inputs:
      * g, a ring map (Macaulay2Doc), corresponding to a
        birational map $f : X \to Y$
      * phi, an instance of the type RationalMapping, a
        rational map between projective varieties $f : X \to Y$
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 1, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
      * CheckBirational => a Boolean value (Macaulay2Doc),
        default value true, whether to check birationality (if it is not
        birational, and CheckBirational is set to true, then an error will be
        thrown)
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume a rational map of schemes is
        dominant, if set to true it can speed up computation
      * Strategy => a symbol (Macaulay2Doc), default value
        HybridStrategy, choose the strategy to use: HybridStrategy,
        SimisStrategy, or ReesStrategy
      * HybridLimit => an integer (Macaulay2Doc), default value 15,
        within HybridStrategy, the option HybridLimit controls how often
        SimisStrategy and ReesStrategy are used, larger numbers means
        SimisStrategy will be executed longer
      * MinorsLimit => an integer (Macaulay2Doc), default value null,
        how many submatrices of a variant of the Jacobian dual matrix to
        consider before switching to a different strategy
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * psi, an instance of the type RationalMapping,
        inverse function of the birational map

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

Given a rational map $f : X \to Y$, inverseOfMap computes the inverse of the
induced map $X \to \overline{f(X)}$, provided it is birational." The target and
source must be varieties; their defining ideals must be prime.

If AssumeDominant is set to true (default is false) then it assumes that the
rational map of projective varieties is dominant, otherwise the function will
compute the image by finding the kernel of $f$.

The Strategy option can be set to HybridStrategy (default), SimisStrategy,
ReesStrategy, or SaturationStrategy.  Note that SimisStrategy will never
terminate for non-birational maps. If CheckBirational is set to false (default
is true), then no check for birationality will be done.  If it is set to true
and the map is not birational, then an error will be thrown if you are not
using SimisStrategy. The option HybridLimit controls HybridStrategy.  Larger
values of HybridLimit (the default value is 15) will mean that SimisStrategy is
executed longer, smaller values will mean that ReesStrategy will be switched to
sooner.

+-----------------------------------------------+
|i1 : R = ZZ/7[x,y,z];                          |
+-----------------------------------------------+
|i2 : S = ZZ/7[a,b,c];                          |
+-----------------------------------------------+
|i3 : h = map(R, S, {y*z, x*z, x*y});           |
|                                               |
|o3 : RingMap R <-- S                           |
+-----------------------------------------------+
|i4 : inverseOfMap (h, Verbosity=>0)            |
|                                               |
|o4 = Proj S - - - > Proj R   {-b*c, -a*c, -a*b}|
|                                               |
|o4 : RationalMapping                           |
+-----------------------------------------------+

Notice that removal of the leading minus signs would not change the projective
map.  Next let us compute the inverse of the blowup of $P^2$ at a point.

+-----------------------------------------------------------------------------+
|i5 : P5 = QQ[a..f];                                                          |
+-----------------------------------------------------------------------------+
|i6 : M = matrix{{a,b,c},{d,e,f}};                                            |
|                                                                             |
|              2       3                                                      |
|o6 : Matrix P5  <-- P5                                                       |
+-----------------------------------------------------------------------------+
|i7 : blowUpSubvar = P5/(minors(2, M)+ideal(b - d));                          |
+-----------------------------------------------------------------------------+
|i8 : h = map(blowUpSubvar, QQ[x,y,z],{a, b, c});                             |
|                                                                             |
|o8 : RingMap blowUpSubvar <-- QQ[x..z]                                       |
+-----------------------------------------------------------------------------+
|i9 : g = inverseOfMap(h, Verbosity=>0)                                       |
|                                                                             |
|                                                   4    3     3     3        |
|o9 = Proj(QQ[x..z]) - - - > Proj blowUpSubvar   {-x , -x y, -x z, -x y,      |
|                                                                             |
|o9 : RationalMapping                                                         |
|-----------------------------------------------------------------------------|
|  2 2    2                                                                   |
|-x y , -x y*z}                                                               |
+-----------------------------------------------------------------------------+
|i10 : baseLocusOfMap(g)                                                      |
|                                                                             |
|o10 = ideal (y, x)                                                           |
|                                                                             |
|o10 : Ideal of QQ[x..z]                                                      |
+-----------------------------------------------------------------------------+
|i11 : baseLocusOfMap(h)                                                      |
|                                                                             |
|o11 = ideal 1                                                                |
|                                                                             |
|o11 : Ideal of blowUpSubvar                                                  |
+-----------------------------------------------------------------------------+

The next example is a birational map on $\mathbb{P}^4$.

+-----------------------------------------------------------------------------+
|i12 : Q=QQ[x,y,z,t,u];                                                       |
+-----------------------------------------------------------------------------+
|i13 : phi=map(Q,Q,matrix{{x^5,y*x^4,z*x^4+y^5,t*x^4+z^5,u*x^4+t^5}});        |
|                                                                             |
|o13 : RingMap Q <-- Q                                                        |
+-----------------------------------------------------------------------------+
|i14 : time inverseOfMap(phi,CheckBirational=>false, Verbosity=>0)            |
| -- used 0.392342s (cpu); 0.38969s (thread); 0s (gc)                         |
|                                                                             |
|                                125   124      120 5    124    100 25        |
|o14 = Proj Q - - - > Proj Q   {x   , x   y, - x   y  + x   z, x   y   -      |
|                                                                             |
|o14 : RationalMapping                                                        |
|-----------------------------------------------------------------------------|
|  104 20       108 15 2      112 10 3     116 5 4    120 5    124      125   |
|5x   y  z + 10x   y  z  - 10x   y  z  + 5x   y z  - x   z  + x   t, - y    + |
|-----------------------------------------------------------------------------|
|   4 120        8 115 2        12 110 3         16 105 4         20 100 5    |
|25x y   z - 300x y   z  + 2300x  y   z  - 12650x  y   z  + 53130x  y   z  -  |
|-----------------------------------------------------------------------------|
|       24 95 6          28 90 7           32 85 8           36 80 9          |
|177100x  y  z  + 480700x  y  z  - 1081575x  y  z  + 2042975x  y  z  -        |
|-----------------------------------------------------------------------------|
|        40 75 10           44 70 11           48 65 12           52 60 13    |
|3268760x  y  z   + 4457400x  y  z   - 5200300x  y  z   + 5200300x  y  z   -  |
|-----------------------------------------------------------------------------|
|        56 55 14           60 50 15           64 45 16           68 40 17    |
|4457400x  y  z   + 3268760x  y  z   - 2042975x  y  z   + 1081575x  y  z   -  |
|-----------------------------------------------------------------------------|
|       72 35 18          76 30 19         80 25 20         84 20 21          |
|480700x  y  z   + 177100x  y  z   - 53130x  y  z   + 12650x  y  z   -        |
|-----------------------------------------------------------------------------|
|     88 15 22       92 10 23      96 5 24    100 25     24 100               |
|2300x  y  z   + 300x  y  z   - 25x  y z   + x   z   - 5x  y   t +            |
|-----------------------------------------------------------------------------|
|    28 95          32 90 2         36 85 3          40 80 4          44 75 5 |
|100x  y  z*t - 950x  y  z t + 5700x  y  z t - 24225x  y  z t + 77520x  y  z t|
|-----------------------------------------------------------------------------|
|         48 70 6           52 65 7           56 60 8           60 55 9       |
|- 193800x  y  z t + 387600x  y  z t - 629850x  y  z t + 839800x  y  z t -    |
|-----------------------------------------------------------------------------|
|       64 50 10           68 45 11           72 40 12           76 35 13     |
|923780x  y  z  t + 839800x  y  z  t - 629850x  y  z  t + 387600x  y  z  t -  |
|-----------------------------------------------------------------------------|
|       80 30 14          84 25 15          88 20 16         92 15 17         |
|193800x  y  z  t + 77520x  y  z  t - 24225x  y  z  t + 5700x  y  z  t -      |
|-----------------------------------------------------------------------------|
|    96 10 18        100 5 19      104 20       48 75 2       52 70   2       |
|950x  y  z  t + 100x   y z  t - 5x   z  t - 10x  y  t  + 150x  y  z*t  -     |
|-----------------------------------------------------------------------------|
|     56 65 2 2        60 60 3 2         64 55 4 2         68 50 5 2          |
|1050x  y  z t  + 4550x  y  z t  - 13650x  y  z t  + 30030x  y  z t  -        |
|-----------------------------------------------------------------------------|
|      72 45 6 2         76 40 7 2         80 35 8 2         84 30 9 2        |
|50050x  y  z t  + 64350x  y  z t  - 64350x  y  z t  + 50050x  y  z t  -      |
|-----------------------------------------------------------------------------|
|      88 25 10 2         92 20 11 2        96 15 12 2        100 10 13 2     |
|30030x  y  z  t  + 13650x  y  z  t  - 4550x  y  z  t  + 1050x   y  z  t  -   |
|-----------------------------------------------------------------------------|
|    104 5 14 2      108 15 2      72 50 3       76 45   3       80 40 2 3    |
|150x   y z  t  + 10x   z  t  - 10x  y  t  + 100x  y  z*t  - 450x  y  z t  +  |
|-----------------------------------------------------------------------------|
|     84 35 3 3        88 30 4 3        92 25 5 3        96 20 6 3            |
|1200x  y  z t  - 2100x  y  z t  + 2520x  y  z t  - 2100x  y  z t  +          |
|-----------------------------------------------------------------------------|
|     100 15 7 3       104 10 8 3       108 5 9 3      112 10 3     96 25 4   |
|1200x   y  z t  - 450x   y  z t  + 100x   y z t  - 10x   z  t  - 5x  y  t  + |
|-----------------------------------------------------------------------------|
|   100 20   4      104 15 2 4      108 10 3 4      112 5 4 4     116 5 4     |
|25x   y  z*t  - 50x   y  z t  + 50x   y  z t  - 25x   y z t  + 5x   z t  -   |
|-----------------------------------------------------------------------------|
| 120 5    124                                                                |
|x   t  + x   u}                                                              |
+-----------------------------------------------------------------------------+

Finally, we do an example of plane Cremona maps whose source is not minimally
embedded.

+-----------------------------------------------------------------------------+
|i15 : R=QQ[x,y,z,t]/(z-2*t);                                                 |
+-----------------------------------------------------------------------------+
|i16 : F = {y*z*(x-z)*(x-2*y), x*z*(y-z)*(x-2*y),y*x*(y-z)*(x-z)};            |
+-----------------------------------------------------------------------------+
|i17 : S = QQ[u,v,w];                                                         |
+-----------------------------------------------------------------------------+
|i18 : ident = rationalMapping map(S, S)                                      |
|                                                                             |
|o18 = Proj S - - - > Proj S   {u, v, w}                                      |
|                                                                             |
|o18 : RationalMapping                                                        |
+-----------------------------------------------------------------------------+
|i19 : h = rationalMapping(R, S, F);                                          |
+-----------------------------------------------------------------------------+
|i20 : g = inverseOfMap(h, Verbosity=>0)                                      |
|                                                                             |
|                                   2 2     2          2      2 2          2  |
|o20 = Proj S - - - > Proj R   {- 2u v  + 8u v*w - 6u*v w - 8u w  + 12u*v*w  -|
|                                                                             |
|o20 : RationalMapping                                                        |
|-----------------------------------------------------------------------------|
|  2 2      2 2     2          2      2 2         2     2 2      2 2     2    |
|4v w , - 2u v  + 6u v*w - 4u*v w - 4u w  + 6u*v*w  - 2v w , - 2u v  + 6u v*w |
|-----------------------------------------------------------------------------|
|      2      2 2         2     2 2     2 2     2          2      2 2         |
|- 6u*v w - 4u w  + 8u*v*w  - 4v w , - u v  + 3u v*w - 3u*v w - 2u w  +       |
|-----------------------------------------------------------------------------|
|      2     2 2                                                              |
|4u*v*w  - 2v w }                                                             |
+-----------------------------------------------------------------------------+
|i21 : h*g == ident                                                           |
|                                                                             |
|o21 = true                                                                   |
+-----------------------------------------------------------------------------+

Caveat
======

The current implementation of this function works only for irreducible
varieties.  Also see the function inverseMap (Cremona), in the
package Cremona, which for some maps from projective space
is faster.  Additionally, also compare with the function
invertBirationalMap (Parametrization), of the package
Parametrization.

See also
========

  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse

Ways to use inverseOfMap:
=========================

  * "inverseOfMap(RationalMapping)"
  * "inverseOfMap(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2281:0.

isBirationalMap -- whether a map between projective varieties is birational
***************************************************************************

  * Usage:
        val = isBirationalMap(Pi)
        val = isBirationalMap(phi)
  * Inputs:
      * Pi, a ring map (Macaulay2Doc), a ring map S to R
        corresponding to X mapping to Y
      * phi, an instance of the type RationalMapping, a
        rational map between projective varieties X to Y
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 1, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume the provided rational map of
        projective varieties is dominant, if set to true it can speed up
        computation
      * Strategy => a symbol (Macaulay2Doc), default value
        HybridStrategy, choose the strategy to use: HybridStrategy,
        SimisStrategy, or ReesStrategy
      * HybridLimit => an integer (Macaulay2Doc), default value 15,
        within HybridStrategy, within HybridStrategy, the option HybridLimit
        controls how often SimisStrategy and ReesStrategy are used
      * MinorsLimit => an integer (Macaulay2Doc), default value null,
        how many submatrices of a variant of the Jacobian dual matrix to
        consider before switching to a different strategy
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * val, a Boolean value (Macaulay2Doc), true if the map is
        birational, false if otherwise

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

The function isBirationalMap computes whether a map between projective
varieties is birational.   The option AssumeDominant being true will cause the
function to assume that the kernel of the associated ring map is zero (default
value is false).  The target and source must be varieties; their defining
ideals must be prime.  Let's check that the plane quadratic Cremona
transformation is birational.

+----------------------------------------------------------------+
|i1 : R=QQ[x,y,z];                                               |
+----------------------------------------------------------------+
|i2 : S=QQ[a,b,c];                                               |
+----------------------------------------------------------------+
|i3 : Pi = map(R, S, {x*y, x*z, y*z});                           |
|                                                                |
|o3 : RingMap R <-- S                                            |
+----------------------------------------------------------------+
|i4 : isBirationalMap(Pi, Verbosity=>0, Strategy=>SimisStrategy )|
|                                                                |
|o4 = true                                                       |
+----------------------------------------------------------------+

We can also verify that a cover of $P^1$ by an elliptic curve is not
birational.

+--------------------------------------+
|i5 : R=QQ[x,y,z]/(x^3+y^3-z^3);       |
+--------------------------------------+
|i6 : S=QQ[s,t];                       |
+--------------------------------------+
|i7 : Pi = map(R, S, {x, y-z});        |
|                                      |
|o7 : RingMap R <-- S                  |
+--------------------------------------+
|i8 : isBirationalMap(Pi, Verbosity=>0)|
|                                      |
|o8 = false                            |
+--------------------------------------+

Note that the Frobenius map is not birational.

+-----------------------------------------------------------------------------+
|i9 : R = ZZ/5[x,y,z]/(x^3+y^3-z^3);                                          |
+-----------------------------------------------------------------------------+
|i10 : S = ZZ/5[a,b,c]/(a^3+b^3-b^3);                                         |
+-----------------------------------------------------------------------------+
|i11 : h = map(R, S, {x^5, y^5, z^5});                                        |
|                                                                             |
|o11 : RingMap R <-- S                                                        |
+-----------------------------------------------------------------------------+
|i12 : isBirationalMap(h, Strategy=>SaturationStrategy)                       |
|isBirationalMap: About to find the image of the map.  If you know the        |
|        you may want to use the AssumeDominant option if this is slow.       |
|isBirationalOntoImageRees:  About to compute the Jacobian Dual Matrix,       |
|         if it is slow, run again and  set Strategy=>HybridStrategy or       |
|isBirationalOntoImageRees: computed Jacobian dual matrix                     |
|                                                                             |
|o12 = false                                                                  |
|-----------------------------------------------------------------------------|
|image,                                                                       |
|                                                                             |
|                                                                             |
| SimisStrategy.                                                              |
+-----------------------------------------------------------------------------+

Caveat
======

Also see the very fast probabilistic birationality checking of the
Cremona, package: isBirational (Cremona).

See also
========

  * isBirationalOntoImage -- whether a map
    between projective varieties is birational onto its image
  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse

Ways to use isBirationalMap:
============================

  * "isBirationalMap(RationalMapping)"
  * "isBirationalMap(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:1737:0.

isBirationalOntoImage -- whether a map between projective varieties is birational onto its image
************************************************************************************************

  * Usage:
        val = isBirationalOntoImage(Pi)
        val = isBirationalOntoImage(phi)
  * Inputs:
      * Pi, a ring map (Macaulay2Doc), A ring map S to R
        corresponding to a rational map between projective varieties
      * phi, an instance of the type RationalMapping, A
        rational map between projective varieties
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 1, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume the provided rational map of
        projective varieties is dominant, if true it can speed up computation
        as a kernel will not be computed
      * Strategy => a symbol (Macaulay2Doc), default value
        HybridStrategy, choose the strategy to use: HybridStrategy,
        SimisStrategy, or ReesStrategy
      * HybridLimit => an integer (Macaulay2Doc), default value 15,
        within HybridStrategy, the option HybridLimit controls how often
        SimisStrategy and ReesStrategy are used, larger numbers means
        SimisStrategy will be executed longer
      * MinorsLimit => an integer (Macaulay2Doc), default value null,
        how many submatrices of a variant of the Jacobian dual matrix to
        consider before switching to a different strategy
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * val, a Boolean value (Macaulay2Doc), true if the map is
        birational onto its image, false if otherwise

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

The function isBirationalOntoImage computes whether $f : X \to Y$ is birational
onto its image.  It is essentially a combination of mapOntoImage with
isBirationalOntoImage.  Setting option AssumeDominant to true will cause the
function to assume that the kernel of the associated ring map is zero (default
value is false).  The source must be a variety; its defining ideal must be
prime.  In the following example, the map is not birational, but it is
birational onto its image.

+----------------------------------------------+
|i1 : R=QQ[x,y];                               |
+----------------------------------------------+
|i2 : S=QQ[a,b,c,d];                           |
+----------------------------------------------+
|i3 : Pi = map(R, S, {x^3, x^2*y, x*y^2, y^3});|
|                                              |
|o3 : RingMap R <-- S                          |
+----------------------------------------------+
|i4 : isBirationalOntoImage(Pi, Verbosity=>0)  |
|                                              |
|o4 = true                                     |
+----------------------------------------------+
|i5 : isBirationalMap(Pi,  Verbosity=>0)       |
|                                              |
|o5 = false                                    |
+----------------------------------------------+

Sub-Hankel matrices (matrices whose ascending skew-diagonal entries are
constant) have homaloidal determinants (the associated partial derivatives
define a Cremona map). For more discussion see:

  * Mostafazadehfard, Maral; Simis, Aron.  Homaloidal determinants. J. Algebra
    450 (2016), 59--101.

Consider the following example illustrating this.

+-----------------------------------------------------------------------------+
|i6 : A = QQ[z_0..z_6];                                                       |
+-----------------------------------------------------------------------------+
|i7 : H=map(A^4,4,(i,j)->A_(i+j));                                            |
|                                                                             |
|             4      4                                                        |
|o7 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i8 : SH=sub(H,{z_5=>0,z_6=>0})                                               |
|                                                                             |
|o8 = | z_0 z_1 z_2 z_3 |                                                     |
|     | z_1 z_2 z_3 z_4 |                                                     |
|     | z_2 z_3 z_4 0   |                                                     |
|     | z_3 z_4 0   0   |                                                     |
|                                                                             |
|             4      4                                                        |
|o8 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i9 : sh=map(A, A, transpose jacobian ideal det SH );                         |
|                                                                             |
|o9 : RingMap A <-- A                                                         |
+-----------------------------------------------------------------------------+
|i10 : isBirationalOntoImage(sh, Verbosity=>0)                                |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : B=QQ[t_0..t_4];                                                        |
+-----------------------------------------------------------------------------+
|i12 : li=map(B,A,matrix{{t_0..t_4,0,0}});                                    |
|                                                                             |
|o12 : RingMap B <-- A                                                        |
+-----------------------------------------------------------------------------+
|i13 : phi=li*sh;                                                             |
|                                                                             |
|o13 : RingMap B <-- A                                                        |
+-----------------------------------------------------------------------------+
|i14 : isBirationalOntoImage(phi, HybridLimit=>2)                             |
|isBirationalOntoImageSimis: About to find the image of the map.  If you know |
|        you may want to use the AssumeDominant option if this is slow.       |
|                                                                             |
|o14 = true                                                                   |
|-----------------------------------------------------------------------------|
|the image,                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * isBirationalMap -- whether a map between projective
    varieties is birational

Ways to use isBirationalOntoImage:
==================================

  * "isBirationalOntoImage(RationalMapping)"
  * "isBirationalOntoImage(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:1806:0.

isEmbedding -- whether a rational map of projective varieties is a closed embedding
***********************************************************************************

  * Usage:
        val = isEmbedding(f)
        val = isEmbedding(phi)
  * Inputs:
      * f, a ring map (Macaulay2Doc), the ring map corresponding
        to $f : X \to Y$
      * phi, an instance of the type RationalMapping, a
        rational map of projective varieties, $f : X \to Y$.
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 1, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume the provided rational map of
        projective varieties is dominant, if set to true it can speed up
        computation
      * Strategy => a symbol (Macaulay2Doc), default value
        HybridStrategy, choose the strategy to use: HybridStrategy,
        SimisStrategy, or ReesStrategy
      * HybridLimit => an integer (Macaulay2Doc), default value 15,
        within HybridStrategy, the option HybridLimit controls how often
        SimisStrategy and ReesStrategy are used,   larger numbers means
        SimisStrategy will be executed longer
      * MinorsLimit => an integer (Macaulay2Doc), default value 0,
        how many submatrices of a variant of the Jacobian dual matrix to
        consider before switching to a different strategy
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * val, a Boolean value (Macaulay2Doc), true if the map is
        an embedding, otherwise false.

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

Given a map of rings, corresponding to a rational map $f : X \to Y$,
isEmbedding determines whether $f$ map embeds $X$ as a closed subscheme into
$Y$.  The target and source must be varieties; their defining ideals must be
prime.  Consider the Veronese embedding.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y];                                                          |
+-----------------------------------------------------------------------------+
|i2 : S = ZZ/7[a,b,c];                                                        |
+-----------------------------------------------------------------------------+
|i3 : h = map(R, S, {x^2, x*y, y^2});                                         |
|                                                                             |
|o3 : RingMap R <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : isEmbedding(h, Verbosity=>1)                                            |
|isEmbedding: About to find the image of the map.  If you know the image,     |
|        you may want to use the AssumeDominant option if this is slow.       |
|inverseOfMapSimis: About to check rank, if this is very slow, you may want to|
|inverseOfMapSimis: rank found, we computed enough of the Groebner basis.     |
|                                                                             |
|o4 = true                                                                    |
|-----------------------------------------------------------------------------|
|try turning QuickRank=>false.                                                |
+-----------------------------------------------------------------------------+

If the option Verbosity is set to 2, the function will produce very detailed
output.  Setting it to 0 will suppress output such output. Now consider the
projection from a point on the plane to the line at infinity.

+------------------------------------+
|i5 : R=QQ[x,y,z];                   |
+------------------------------------+
|i6 : S=QQ[a,b];                     |
+------------------------------------+
|i7 : h=rationalMapping(R, S, {y,z});|
+------------------------------------+
|i8 : isEmbedding(h, Verbosity=>0)   |
|                                    |
|o8 = false                          |
+------------------------------------+

That is obviously not an embedding.  It is even not an embedding when we
restrict to a quadratic curve, even though it is a regular map.

+----------------------------------+
|i9 : R=QQ[x,y,z]/(x^2+y^2-z^2);   |
+----------------------------------+
|i10 : S=QQ[a,b];                  |
+----------------------------------+
|i11 : h=map(R,S, {y,z});          |
|                                  |
|o11 : RingMap R <-- S             |
+----------------------------------+
|i12 : isRegularMap(h)             |
|                                  |
|o12 = true                        |
+----------------------------------+
|i13 : isEmbedding(h, Verbosity=>0)|
|                                  |
|o13 = false                       |
+----------------------------------+

If the option AssumeDominant is set to true, the function won't compute the
kernel of the ring map.  Otherwise it will.

The remaining options, Strategy, HybridLimit, MinorsLimit, and CheckBirational
are simply passed when isEmbedding calls inverseOfMap.  Note, this function,
isEmbedding, will only behave properly if CheckBirational is set to true.

We conclude by considering the map from $P^1$ to a cuspidal curve in $P^2$.
This is not an embedding, but if we take the strict transform in the blowup of
$P^2$, it is an embedding.

+---------------------------------------------------------------------+
|i14 : R = ZZ/103[x,y,z];                                             |
+---------------------------------------------------------------------+
|i15 : T = ZZ/103[u,v];                                               |
+---------------------------------------------------------------------+
|i16 : P2 = Proj R;                                                   |
+---------------------------------------------------------------------+
|i17 : P1 = Proj T;                                                   |
+---------------------------------------------------------------------+
|i18 : phi = rationalMapping(P2, P1, {u^3, u^2*v, v^3});              |
+---------------------------------------------------------------------+
|i19 : isEmbedding(phi, Verbosity=>0)                                 |
|                                                                     |
|o19 = false                                                          |
+---------------------------------------------------------------------+
|i20 : P5ring = ZZ/103[a..f];                                         |
+---------------------------------------------------------------------+
|i21 : M = matrix{{a,b,c},{d,e,f}};                                   |
|                                                                     |
|                   2           3                                     |
|o21 : Matrix P5ring  <-- P5ring                                      |
+---------------------------------------------------------------------+
|i22 : blowUpSubvar = Proj(P5ring/(minors(2, M)+ideal(b - d)));       |
+---------------------------------------------------------------------+
|i23 : tau = rationalMapping(P2, blowUpSubvar,{a, b, c}); --the blowup|
+---------------------------------------------------------------------+
|i24 : tauInverse = tau^-1; --the inverse blowup                      |
+---------------------------------------------------------------------+
|i25 : isEmbedding(tauInverse*phi, Verbosity => 0)                    |
|                                                                     |
|o25 = true                                                           |
+---------------------------------------------------------------------+

See also
========

  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse

Ways to use isEmbedding:
========================

  * "isEmbedding(RationalMapping)"
  * "isEmbedding(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2021:0.

isRegularMap -- whether a map to projective space is regular
************************************************************

  * Usage:
        b = isRegularMap(f)
  * Inputs:
      * f, a ring map (Macaulay2Doc), a ring map corresponding
        to a rational map of projective varieties
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 0, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
  * Outputs:
      * b, a Boolean value (Macaulay2Doc),

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

This function runs baseLocusOfMap(f) and checks whether the ideal defining the
base locus is the whole ring.

+-----------------------------------------------------+
|i1 : P5 = QQ[a..f];                                  |
+-----------------------------------------------------+
|i2 : P2 = QQ[x,y,z];                                 |
+-----------------------------------------------------+
|i3 : M = matrix{{a,b,c},{d,e,f}};                    |
|                                                     |
|              2       3                              |
|o3 : Matrix P5  <-- P5                               |
+-----------------------------------------------------+
|i4 : blowUpSubvar = P5/(minors(2, M) + ideal(b - d));|
+-----------------------------------------------------+
|i5 : f = map(blowUpSubvar, P2, {a, b, c});           |
|                                                     |
|o5 : RingMap blowUpSubvar <-- P2                     |
+-----------------------------------------------------+
|i6 : isRegularMap(f)                                 |
|                                                     |
|o6 = true                                            |
+-----------------------------------------------------+

Ways to use isRegularMap:
=========================

  * "isRegularMap(RationalMapping)"
  * "isRegularMap(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2194:0.

isSameMap -- whether two rational maps to between projective varieties are really the same
******************************************************************************************

  * Usage:
        b = isSameMap(f1, f2)
        phi == psi
        b = isSameMap(phi, psi)
  * Inputs:
      * f1, a ring map (Macaulay2Doc), a map of rings
        corresponding to a rational map between projective varieties
      * f2, a ring map (Macaulay2Doc), a map of rings
        corresponding to a rational map between projective varieties
      * phi, an instance of the type RationalMapping, a
        map between projective varieties
      * psi, an instance of the type RationalMapping, a
        rational map between projective varieties
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), true if the rational
        maps are the same, false otherwise.

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

Checks whether two rational maps between projective varieties are really the
same (that is, agree on a dense open set).

+---------------------------------------+
|i1 : R=QQ[x,y,z];                      |
+---------------------------------------+
|i2 : S=QQ[a,b,c];                      |
+---------------------------------------+
|i3 : f1=map(R, S, {y*z,x*z,x*y});      |
|                                       |
|o3 : RingMap R <-- S                   |
+---------------------------------------+
|i4 : f2=map(R, S, {x*y*z,x^2*z,x^2*y});|
|                                       |
|o4 : RingMap R <-- S                   |
+---------------------------------------+
|i5 : isSameMap(f1,f2)                  |
|                                       |
|o5 = true                              |
+---------------------------------------+

The Cremona transformation is not the identity, but its square is.

+-----------------------------------------------+
|i6 : R = ZZ/7[x,y,z]                           |
|                                               |
|o6 = R                                         |
|                                               |
|o6 : PolynomialRing                            |
+-----------------------------------------------+
|i7 : phi = rationalMapping(R, R, {y*z,x*z,x*y})|
|                                               |
|o7 = Proj R - - - > Proj R   {y*z, x*z, x*y}   |
|                                               |
|o7 : RationalMapping                           |
+-----------------------------------------------+
|i8 : ident = rationalMapping(R, R, {x,y,z})    |
|                                               |
|o8 = Proj R - - - > Proj R   {x, y, z}         |
|                                               |
|o8 : RationalMapping                           |
+-----------------------------------------------+
|i9 : phi == ident                              |
|                                               |
|o9 = false                                     |
+-----------------------------------------------+
|i10 : phi^2 == ident                           |
|                                               |
|o10 = true                                     |
+-----------------------------------------------+

Ways to use isSameMap:
======================

  * "isSameMap(RationalMapping,RationalMapping)"
  * "isSameMap(RingMap,RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2164:0.

jacobianDualMatrix -- computes the Jacobian dual matrix
*******************************************************

  * Usage:
        M = jacobianDualMatrix(p)
        M = jacobianDualMatrix(phi)
  * Inputs:
      * phi, an instance of the type RationalMapping, a
        rational map between projective varieties
      * p, a ring map (Macaulay2Doc), ring map corresponding to
        a rational map between projective varieties
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        ReesStrategy, choose the strategy to use: ReesStrategy or
        SaturationStrategy
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume the provided rational map of
        projective varieties is dominant, if set to true it can speed up
        computation
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * M, a matrix (Macaulay2Doc), a matrix $M$ over the
        coordinate ring of the image, the kernel of $M$ describes the syzygies
        of the inverse map, if it exists.

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

The Jacobian dual matrix is a matrix whose kernel describes the syzygies of the
matrix corresponding to the inverse map. For more information, see

  * Doria, A. V.; Hassanzadeh, S. H.; Simis, A. A characteristic-free criterion
    of birationality. Adv. Math. 230 (2012), no. 1, 390--413.

This is mostly an internal function. It is used when checking whether a map is
birational and when computing the inverse map.  If the AssumeDominant option is
set to true, it assumes that the kernel of the associated ring map is zero
(default value is false).  Valid values for the Strategy option are
ReesStrategy and SaturationStrategy.

+-----------------------------------------------------------------------------+
|i1 : R=QQ[x,y];                                                              |
+-----------------------------------------------------------------------------+
|i2 : S=QQ[a,b,c,d];                                                          |
+-----------------------------------------------------------------------------+
|i3 : Pi = map(R, S, {x^3, x^2*y, x*y^2, y^3});                               |
|                                                                             |
|o3 : RingMap R <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : jacobianDualMatrix(Pi, Strategy=>SaturationStrategy)                    |
|                                                                             |
|o4 = | -d -c -b 0 0 0 |                                                      |
|     | c  b  a  0 0 0 |                                                      |
|                                                                             |
|            /               S               \2     /               S         |
|o4 : Matrix |-------------------------------|  <-- |-------------------------|
|            |  2                    2       |      |  2                    2 |
|            \(c  - b*d, b*c - a*d, b  - a*c)/      \(c  - b*d, b*c - a*d, b  |
|-----------------------------------------------------------------------------|
|      \6                                                                     |
|------|                                                                      |
|      |                                                                      |
|- a*c)/                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse

Ways to use jacobianDualMatrix:
===============================

  * "jacobianDualMatrix(RationalMapping)"
  * "jacobianDualMatrix(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:1897:0.

map(RationalMapping) -- the ring map associated to a RationalMapping between projective varieties
*************************************************************************************************

  * Function: map (Macaulay2Doc),

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

Given a RationalMapping between projective varieties, this returns the
associated map between projective varieties.

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

  * map(RationalMapping) -- the ring map
    associated to a RationalMapping between projective varieties
-------------------------------------------------------------------------------

The source of this document is in RationalMaps.m2:1642:0.

mapOntoImage -- the induced map from a variety to the closure of its image under a rational map
***********************************************************************************************

  * Usage:
        h = mapOntoImage(f)
        psi = mapOntoImage(phi)
  * Inputs:
      * f, a ring map (Macaulay2Doc), the ring map corresponding
        to a rational map $\phi$ of projective varieties
      * phi, an instance of the type RationalMapping, a
        rational map $\phi$ of projective varieties
  * Optional inputs (Macaulay2Doc),:
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * h, a ring map (Macaulay2Doc), the map of rings
        corresponding to $X \to \overline{\phi(X)}$.
      * psi, an instance of the type RationalMapping,
        the rational map

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

Given $f : X \to Y$ mapOntoImage returns $X \to \overline{\phi(X)}$.
Alternately, given $f: S \to R$, mapOntoImage just returns $S/(kernel f) \to
R$.  mapOntoImage first computes whether the kernel is $0$ without calling
ker (Macaulay2Doc), which can have speed advantages.

+--------------------------------------------------+
|i1 : R = QQ[x,y];                                 |
+--------------------------------------------------+
|i2 : S = QQ[a,b,c];                               |
+--------------------------------------------------+
|i3 : f = map(R, S, {x^2, x*y, y^2});              |
|                                                  |
|o3 : RingMap R <-- S                              |
+--------------------------------------------------+
|i4 : mapOntoImage(f)                              |
|                                                  |
|                 S       2        2               |
|o4 = map (R, --------, {x , x*y, y })             |
|              2                                   |
|             b  - a*c                             |
|                                                  |
|                       S                          |
|o4 : RingMap R <-- --------                       |
|                    2                             |
|                   b  - a*c                       |
+--------------------------------------------------+
|i5 : phi = rationalMapping f                      |
|                                                  |
|                               2        2         |
|o5 = Proj R - - - > Proj S   {x , x*y, y }        |
|                                                  |
|o5 : RationalMapping                              |
+--------------------------------------------------+
|i6 : mapOntoImage(phi)                            |
|                                                  |
|                        /    S   \     2        2 |
|o6 = Proj R - - - > Proj|--------|   {x , x*y, y }|
|                        | 2      |                |
|                        \b  - a*c/                |
|                                                  |
|o6 : RationalMapping                              |
+--------------------------------------------------+

Ways to use mapOntoImage:
=========================

  * "mapOntoImage(RationalMapping)"
  * "mapOntoImage(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:1935:0.

MinorsLimit -- an option to limit the number of random minors computed
**********************************************************************

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

One of the ways to invert a map is to find a nonzero minor of a variant of the
jacobianDualMatrix. This function controls how many minors (heuristically
chosen via FastMinors) to check before switching to
another strategy (involving computing a syzygy). Setting it to zero will mean
no minors are checked. If it is left as null (the default), these functions
will determine a value using a heuristic that depends on the varieties
involved.

See also
========

  * inverseOfMap -- inverse of a birational map between
    projective varieties

Functions with optional argument named MinorsLimit:
===================================================

  * "inverseOfMap(...,MinorsLimit=>...)" -- see inverseOfMap,
    -- inverse of a birational map between projective varieties
  * "isBirationalMap(...,MinorsLimit=>...)" -- see isBirationalMap,
    -- whether a map between projective varieties is
    birational
  * "isBirationalOntoImage(...,MinorsLimit=>...)" -- see
    isBirationalOntoImage, -- whether a map between
    projective varieties is birational onto its image
  * "isEmbedding(...,MinorsLimit=>...)" -- see isEmbedding,
    -- whether a rational map of projective varieties is a closed embedding
  * "sourceInversionFactor(...,MinorsLimit=>...)" -- see
    sourceInversionFactor, -- computes the common factor
    among the components of the composition of the inverse map and the original
    map

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

The object MinorsLimit, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1424:0.

QuickRank --  an option for controlling how rank is computed
************************************************************

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

If set to true, then checking whether rank is at least a certain number will be
computed via the package FastMinors.

See also
========

  * inverseOfMap -- inverse of a birational map between
    projective varieties

Functions with optional argument named QuickRank:
=================================================

  * "idealOfImageOfMap(...,QuickRank=>...)" -- see idealOfImageOfMap,
    -- finds defining equations for the image of a rational
    map between varieties or schemes
  * "inverseOfMap(...,QuickRank=>...)" -- see inverseOfMap,
    -- inverse of a birational map between projective varieties
  * "isBirationalMap(...,QuickRank=>...)" -- see isBirationalMap,
    -- whether a map between projective varieties is
    birational
  * "isBirationalOntoImage(...,QuickRank=>...)" -- see
    isBirationalOntoImage, -- whether a map between
    projective varieties is birational onto its image
  * "isEmbedding(...,QuickRank=>...)" -- see isEmbedding, --
    whether a rational map of projective varieties is a closed embedding
  * "jacobianDualMatrix(...,QuickRank=>...)" -- see jacobianDualMatrix,
    -- computes the Jacobian dual matrix
  * "mapOntoImage(...,QuickRank=>...)" -- see mapOntoImage,
    -- the induced map from a variety to the closure of its image under a
    rational map
  * "sourceInversionFactor(...,QuickRank=>...)" -- see
    sourceInversionFactor, -- computes the common factor
    among the components of the composition of the inverse map and the original
    map

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

The object QuickRank, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1432:0.

RationalMapping -- a rational mapping between projective varieties
******************************************************************

  * Usage:
        phi = rationalMapping(f)
        phi = rationalMapping(targetRing, sourceRing, l)
        phi = rationalMapping(targetRing, sourceRing, m)
        phi = rationalMapping(targetVariety, sourceVariety, l)
        phi = rationalMapping(targetVariety, sourceVariety, m)
  * Inputs:
      * f, a ring map (Macaulay2Doc), a ring map corresponding
        to the rational map between varieties
      * targetRing, a ring (Macaulay2Doc), the ring corresponding
        to the source variety
      * sourceRing, a ring (Macaulay2Doc), the ring corresponding
        to the target variety
      * targetVariety, a projective variety (Varieties),
        the target variety
      * sourceVariety, a projective variety (Varieties),
        the source variety
      * l, a basic list (Macaulay2Doc), the list of elements
        describing the map
      * m, a matrix (Macaulay2Doc), the matrix describing the map

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

A RationalMapping is a Type that is used to treat maps between projective
varieties  geometrically.  It stores essentially equivalent data to the
corresponding map between the homogeneous coordinate rings.  The way to
construct the object is to use the function rationalMapping.

For example, the following is a Cremona transformation on $P^2$ constructed in
multiple ways (in this case, the entries describing the map all have degree 2).

+--------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : P2 = Proj(R)                                       |
|                                                        |
|o2 = P2                                                 |
|                                                        |
|o2 : ProjectiveVariety                                  |
+--------------------------------------------------------+
|i3 : phi1 = rationalMapping(P2, P2, {y*z,x*z,x*y})      |
|                                                        |
|o3 = P2 - - - > P2   {y*z, x*z, x*y}                    |
|                                                        |
|o3 : RationalMapping                                    |
+--------------------------------------------------------+
|i4 : phi2 = rationalMapping(R, R, matrix{{y*z,x*z,x*y}})|
|                                                        |
|o4 = P2 - - - > P2   {y*z, x*z, x*y}                    |
|                                                        |
|o4 : RationalMapping                                    |
+--------------------------------------------------------+
|i5 : phi3 = rationalMapping(map(R, R, {y*z,x*z,x*y}))   |
|                                                        |
|o5 = P2 - - - > P2   {y*z, x*z, x*y}                    |
|                                                        |
|o5 : RationalMapping                                    |
+--------------------------------------------------------+

The source and target can also be different.  For example, consider the
following map from $P^1$ to a nodal cubic in $P^2$.

+----------------------------------------------------------------+
|i6 : S = QQ[x,y,z];                                             |
+----------------------------------------------------------------+
|i7 : P2 = Proj S;                                               |
+----------------------------------------------------------------+
|i8 : R = QQ[a,b];                                               |
+----------------------------------------------------------------+
|i9 : P1 = Proj R;                                               |
+----------------------------------------------------------------+
|i10 : phi = rationalMapping(P2, P1, {b*a*(a-b), a^2*(a-b), b^3})|
|                                                                |
|                        2       2   3    2    3                 |
|o10 = P1 - - - > P2   {a b - a*b , a  - a b, b }                |
|                                                                |
|o10 : RationalMapping                                           |
+----------------------------------------------------------------+
|i11 : h = map(R, S, {b*a*(a-b), a^2*(a-b), b^3})                |
|                                                                |
|                   2       2   3    2    3                      |
|o11 = map (R, S, {a b - a*b , a  - a b, b })                    |
|                                                                |
|o11 : RingMap R <-- S                                           |
+----------------------------------------------------------------+
|i12 : psi = rationalMapping h                                   |
|                                                                |
|                        2       2   3    2    3                 |
|o12 = P1 - - - > P2   {a b - a*b , a  - a b, b }                |
|                                                                |
|o12 : RationalMapping                                           |
+----------------------------------------------------------------+
|i13 : phi == psi                                                |
|                                                                |
|o13 = true                                                      |
+----------------------------------------------------------------+

Notice that when defining a map between projective varieties, we keep the
target then source input convention.

Warning, the list or matrix describing the map needs every entry to have the
same degree.

See also
========

  * RationalMapping * RationalMapping
    -- compose rational maps between projective varieties
  * RationalMapping == RationalMapping -- whether two
    rational maps to between projective varieties are really the same

Functions and methods returning an object of class RationalMapping:
===================================================================

  * RationalMapping * RationalMapping
    -- compose rational maps between projective varieties
  * "RationalMapping ^ ZZ" -- see RationalMapping * RationalMapping,
    -- compose rational maps between
    projective varieties

Methods that use an object of class RationalMapping:
====================================================

  * "baseLocusOfMap(RationalMapping)" -- see baseLocusOfMap,
    -- the base locus of a map from a projective variety to
    projective space
  * "idealOfImageOfMap(RationalMapping)" -- see idealOfImageOfMap,
    -- finds defining equations for the image of a rational
    map between varieties or schemes
  * "inverseOfMap(RationalMapping)" -- see inverseOfMap, --
    inverse of a birational map between projective varieties
  * "isBirationalMap(RationalMapping)" -- see isBirationalMap,
    -- whether a map between projective varieties is
    birational
  * "isBirationalOntoImage(RationalMapping)" -- see
    isBirationalOntoImage, -- whether a map between
    projective varieties is birational onto its image
  * "isEmbedding(RationalMapping)" -- see isEmbedding, --
    whether a rational map of projective varieties is a closed embedding
  * "isRegularMap(RationalMapping)" -- see isRegularMap, --
    whether a map to projective space is regular
  * "isSameMap(RationalMapping,RationalMapping)" -- see isSameMap,
    -- whether two rational maps to between projective varieties are
    really the same
  * "RationalMapping == RationalMapping" -- see isSameMap, --
    whether two rational maps to between projective varieties are really the
    same
  * "jacobianDualMatrix(RationalMapping)" -- see jacobianDualMatrix,
    -- computes the Jacobian dual matrix
  * map(RationalMapping) -- the ring map
    associated to a RationalMapping between projective varieties
  * "mapOntoImage(RationalMapping)" -- see mapOntoImage, --
    the induced map from a variety to the closure of its image under a rational
    map
  * net(RationalMapping) (missing documentation)
  * source(RationalMapping) -- returns the
    source or target of a RationalMapping between projective varieties.
  * "target(RationalMapping)" -- see source(RationalMapping),
    -- returns the source or target of a
    RationalMapping between projective varieties.

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

The object RationalMapping, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1593:0.

RationalMapping * RationalMapping -- compose rational maps between projective varieties
***************************************************************************************

  * Operator: * (Macaulay2Doc),

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

This allows one to compose two rational maps between projective varieties.

+--------------------------------------------------+
|i1 : R = QQ[x,y,z]                                |
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : PolynomialRing                               |
+--------------------------------------------------+
|i2 : P2 = Proj(R)                                 |
|                                                  |
|o2 = P2                                           |
|                                                  |
|o2 : ProjectiveVariety                            |
+--------------------------------------------------+
|i3 : phi = rationalMapping (P2, P2, {y*z,x*z,x*y})|
|                                                  |
|o3 = P2 - - - > P2   {y*z, x*z, x*y}              |
|                                                  |
|o3 : RationalMapping                              |
+--------------------------------------------------+
|i4 : ident = rationalMapping (P2, P2, {x,y,z})    |
|                                                  |
|o4 = P2 - - - > P2   {x, y, z}                    |
|                                                  |
|o4 : RationalMapping                              |
+--------------------------------------------------+
|i5 : phi*phi == ident                             |
|                                                  |
|o5 = true                                         |
+--------------------------------------------------+

Raising a map to the negative first power means computing the inverse
birational map.  Raising a map to the first power simply returns the map
itself.  In the next example we compute the blowup of a point on $P^2$ and its
inverse.

+-----------------------------------------------------------------------------+
|i6 : P5ring = ZZ/103[a..f];                                                  |
+-----------------------------------------------------------------------------+
|i7 : R = ZZ/103[x,y,z];                                                      |
+-----------------------------------------------------------------------------+
|i8 : P2 = Proj R;                                                            |
+-----------------------------------------------------------------------------+
|i9 : identP2 = rationalMapping(P2, P2, {x,y,z});                             |
+-----------------------------------------------------------------------------+
|i10 : M = matrix{{a,b,c},{d,e,f}};                                           |
|                                                                             |
|                   2           3                                             |
|o10 : Matrix P5ring  <-- P5ring                                              |
+-----------------------------------------------------------------------------+
|i11 : blowUp = Proj(P5ring/(minors(2, M)+ideal(b - d)));                     |
+-----------------------------------------------------------------------------+
|i12 : identBlowUp = rationalMapping(blowUp, blowUp, {a,b,c,d,e,f});          |
+-----------------------------------------------------------------------------+
|i13 : tau = rationalMapping(P2, blowUp,{a, b, c});                           |
+-----------------------------------------------------------------------------+
|i14 : tauInverse = tau^-1;                                                   |
+-----------------------------------------------------------------------------+
|i15 : tau*tauInverse == identP2 --a map composed with its inverse is the     |
|                                                                             |
|o15 = true                                                                   |
|-----------------------------------------------------------------------------|
|identity                                                                     |
+-----------------------------------------------------------------------------+
|i16 : tauInverse*tau == identBlowUp                                          |
|                                                                             |
|o16 = true                                                                   |
+-----------------------------------------------------------------------------+

Note that one can only raise maps to powers (with the exception of 1 and -1) if
the source and target are the same.  In that case, raising a map to a negative
power means compose the inverse of a map with itself.  We illustrate this with
the quadratic transformation on $P^2$ that we started with (an transformation
of order 2 in the Cremona group).

+---------------------+
|i17 : phi^3 == phi^-1|
|                     |
|o17 = true           |
+---------------------+
|i18 : phi^-2 == ident|
|                     |
|o18 = true           |
+---------------------+
|i19 : phi^1 == ident |
|                     |
|o19 = false          |
+---------------------+

See also
========

  * isSameMap -- whether two rational maps to between
    projective varieties are really the same

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

  * RationalMapping * RationalMapping
    -- compose rational maps between projective varieties
-------------------------------------------------------------------------------

The source of this document is in RationalMaps.m2:1632:0.

ReesStrategy -- a strategy for determining whether a map is birational and computing its inverse
************************************************************************************************

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

ReesStrategy is a valid value for the Strategy Option for inverseOfMap,
isBirationalMap, and isEmbedding. By choosing Strategy=>ReesStrategy, the ideal
of definition of the Rees algebra is computed by the known elimination
technique. This technique is described in Proposition 1.5 on page 21 in the
book

  * Vasconcelos, Wolmer.  Integral closure. Springer Monographs in Mathematics.
    Springer-Verlag, Berlin,2005. xii+519 pp.

See also
========

  * SaturationStrategy -- a strategy for determining
    whether a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse

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

The object ReesStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1491:0.

SaturateOutput -- whether the value returned should be saturated
****************************************************************

  * Usage:
        SaturateOutput=>b

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

  If SaturateOutput is true (the default), then functions will saturate their
output. Otherwise they will not.  It may be beneficial not to saturate in
certain circumstances as saturation may slow computation.

Functions with optional argument named SaturateOutput:
======================================================

  * "baseLocusOfMap(...,SaturateOutput=>...)" -- see baseLocusOfMap,
    -- the base locus of a map from a projective variety to
    projective space

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

The object SaturateOutput, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1441:0.

SaturationStrategy -- a strategy for determining whether a map is birational and computing its inverse
******************************************************************************************************

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

SaturationStrategy is a valid value for the Strategy Option for inverseOfMap,
isBirationalMap, and isEmbedding. By choosing Strategy=>SaturationStrategy, the
equations of the ideal of definition of the Rees algebra are generated by
saturating the ideal of definition of the symmetric algebra into a non-zero
element. Notice that in this package (and in particular, in this Strategy
option) the rings are assumed to be integral domains. This Strategy appears to
be slower in some examples.

See also
========

  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse

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

The object SaturationStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1509:0.

SimisStrategy -- a strategy for determining whether a map is birational and computing its inverse
*************************************************************************************************

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

SimisStrategy is a valid value for the Strategy Option of inverseOfMap,
isBirationalMap, and isEmbedding. Considering the bigraded structure of the
equations of the ideal of definition of a Rees algebra, SimisStrategy looks for
all Gröbner bases where the degree is (1, n) for some natural number n. The
advantage of this restriction is that this part of the Rees ideal is enough to
decide birationality and to compute the inverse map; this strategy reduces
computation time. A disadvantage of this Strategy is that if the given map is
not birational this Strategy may never end because the jacobianDualMatrix will
not attain its maximum rank. To circumvent this problem we implemented
HybridStrategy.

See also
========

  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * SaturationStrategy -- a strategy for determining
    whether a map is birational and computing its inverse
  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse

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

The object SimisStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in RationalMaps.m2:1528:0.

source(RationalMapping) -- returns the source or target of a RationalMapping between projective varieties.
**********************************************************************************************************

  * Function: source (Macaulay2Doc),

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

Given a RationalMapping between projective varieties these functions can be
used to return the source or target.

+-----------------------------+
|i1 : R = QQ[a,b];            |
+-----------------------------+
|i2 : S = QQ[x,y,z];          |
+-----------------------------+
|i3 : P2 = Proj R;            |
+-----------------------------+
|i4 : P3 = Proj S;            |
+-----------------------------+
|i5 : f = map(R, S, {a,b,0}); |
|                             |
|o5 : RingMap R <-- S         |
+-----------------------------+
|i6 : phi = rationalMapping f;|
+-----------------------------+
|i7 : source phi              |
|                             |
|o7 = P2                      |
|                             |
|o7 : ProjectiveVariety       |
+-----------------------------+
|i8 : target phi              |
|                             |
|o8 = P3                      |
|                             |
|o8 : ProjectiveVariety       |
+-----------------------------+
|i9 : source f                |
|                             |
|o9 = S                       |
|                             |
|o9 : PolynomialRing          |
+-----------------------------+
|i10 : target f               |
|                             |
|o10 = R                      |
|                             |
|o10 : PolynomialRing         |
+-----------------------------+

Note that the source of phi corresponds to the target of f and the target of
phi corresponds to the source of f.

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

  * source(RationalMapping) -- returns the
    source or target of a RationalMapping between projective varieties.
-------------------------------------------------------------------------------

The source of this document is in RationalMaps.m2:1666:0.

sourceInversionFactor -- computes the common factor among the components of the composition of the inverse map and the original map
***********************************************************************************************************************************

  * Usage:
        s = sourceInversionFactor(g)
  * Inputs:
      * g, a ring map (Macaulay2Doc), a birational map $f : X
        \to Y$.
  * Optional inputs (Macaulay2Doc),:
      * Verbosity => an integer (Macaulay2Doc), default value 1, if 0
        then silence the function, if 1 then generate informative output which
        can be used to adjust strategies, if > 1 then generate a detailed
        description of the execution
      * CheckBirational => a Boolean value (Macaulay2Doc),
        default value false, whether to check birationality (if it is not
        birational, and CheckBirational is set to true, then an error will be
        thrown)
      * Strategy => a symbol (Macaulay2Doc), default value
        HybridStrategy, choose the strategy to use: HybridStrategy,
        SimisStrategy, or ReesStrategy
      * HybridLimit => an integer (Macaulay2Doc), default value 15,
        within HybridStrategy, the option HybridLimit controls how often
        SimisStrategy and ReesStrategy are used, larger numbers means
        SimisStrategy will be executed longer
      * MinorsLimit => an integer (Macaulay2Doc), default value 0,
        how many submatrices of a variant of the Jacobian dual matrix to
        consider before switching to a different strategy
      * AssumeDominant => a Boolean value (Macaulay2Doc),
        default value false, whether to assume a rational map of schemes is
        dominant, if set to true it can speed up computation
      * QuickRank => a Boolean value (Macaulay2Doc), default
        value true, whether to compute rank via the package FastMinors,
  * Outputs:
      * s, a ring element (Macaulay2Doc), an element of the
        coordinate ring of $X$ .

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

Given a map $f : X \to Y$, sourceInversionFactor computes the common factor
among the components of, $f^{(-1)}$ composed with $f$, which is an element of
the coordinate ring of $X$.

If AssumeDominant is set to true (default is false) then it assumes that the
rational map of projective varieties is dominant, otherwise the function will
compute the image by finding the kernel of $f$.

The Strategy option can be set to HybridStrategy (default), SimisStrategy,
ReesStrategy, or SaturationStrategy.  Note SimisStrategy will never terminate
for non-birational maps. If CheckBirational is set to false (default is true),
then no check for birationality will be done.  If it is set to true and the map
is not birational, then an error will be thrown if you are not using
SimisStrategy. The option HybridLimit controls HybridStrategy.  Larger values
of HybridLimit (the default value is 15) will mean that SimisStrategy is
executed longer, smaller values will mean that ReesStrategy will be switched to
sooner.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y,z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : S = ZZ/7[a,b,c];                                                        |
+-----------------------------------------------------------------------------+
|i3 : h = map(R, S, {y*z, x*z, x*y});                                         |
|                                                                             |
|o3 : RingMap R <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : sourceInversionFactor h                                                 |
|sourceInversionFactor: About to find the image of the map.  If you know the i|
|        you may want to use the AssumeDominant option if this is slow.       |
|inverseOfMapSimis: About to find the image of the map.  If you know the image|
|        you may want to use the AssumeDominant option if this is slow.       |
|inverseOfMapSimis: About to check rank, if this is very slow, you may want to|
|inverseOfMapSimis: rank found, we computed enough of the Groebner basis.     |
|                                                                             |
|o4 = x*y*z                                                                   |
|                                                                             |
|o4 : R                                                                       |
|-----------------------------------------------------------------------------|
|mage,                                                                        |
|                                                                             |
|,                                                                            |
|                                                                             |
| try turning QuickRank=>false.                                               |
+-----------------------------------------------------------------------------+
+---------------------------------------------+
|i5 : S=QQ[a,b,c,d];                          |
+---------------------------------------------+
|i6 : g=(b^2-a*c)*c*d;                        |
+---------------------------------------------+
|i7 : phi=map(S,S,transpose jacobian ideal g);|
|                                             |
|o7 : RingMap S <-- S                         |
+---------------------------------------------+
|i8 : sourceInversionFactor(phi, Verbosity=>0)|
|                                             |
|      2 4 2      5 2                         |
|o8 = b c d  - a*c d                          |
|                                             |
|o8 : S                                       |
+---------------------------------------------+

Caveat
======

The current implementation of this function works only for irreducible
varieties..  Also see the function inverseMap (Cremona), in
the package Cremona, which for some maps from projective
space is faster.  Additionally, also compare with the function
invertBirationalMap (Parametrization), of the package
Parametrization.

See also
========

  * HybridStrategy -- A strategy for determining whether
    a map is birational and computing its inverse
  * SimisStrategy -- a strategy for determining whether a
    map is birational and computing its inverse
  * ReesStrategy -- a strategy for determining whether a
    map is birational and computing its inverse

Ways to use sourceInversionFactor:
==================================

  * "sourceInversionFactor(RingMap)"

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

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

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

The source of this document is in RationalMaps.m2:2342:0.