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

ToricHigherDirectImages -- computations involving pushforwards and higher direct images of toric maps
*****************************************************************************************************

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

Given a morphism of varieties $\varphi \colon X \rightarrow Y$, we have the
pushforward functor $\varphi_*$ from the category of coherent sheaves on $X$ to
coherent sheaves on $Y$. This functor is not right-exact, and so there is a
right-derived functor $R^i \varphi_*$ from the bounded derived category
$D^b(X)$ to $D^b(Y)$, which we call the higher direct image functor. When both
$X$ and $Y$ are toric varieties, coherent sheaves arise from finitely generated
multigraded modules over their Cox rings. Thus, for a given coherent sheaf
$\mathcal{F}$, there are finitely generated graded modules over the Cox ring of
$Y$ which sheafifies to $R^i \varphi_* \mathcal{F}$.

The purpose of this package is to compute (higher) direct images of toric
morphisms $\varphi \colon X \rightarrow Y$ between smooth projective toric
varieties. This is currently implemented in two situations:

1) When $\varphi$ is a toric fibration, i.e. a surjective toric morphism with
$\varphi_* \mathcal{O}_X = \mathcal{O}_Y$, then the method \texttt{HDI} allows
one to compute the higher direct images of a line bundle $\mathcal{O}_X(D)$ on
$X$. In "Reduced \v{C}ech complexes and computing higher direct images under
toric maps", M. Roth provides a constructive method for producing this module
and S. Zotine adapts that method into an algorithm. This package provides the
implementation of this algorithm.

For instance, if $X$ is a blowup of $\mathbb{P}^2$, then the first higher
direct image of $O_X(3E)$ is nontrivial, where $E$ is the exceptional divisor.

+-------------------------------------------------+
|i1 : X = hirzebruchSurface 1;                    |
+-------------------------------------------------+
|i2 : Y = toricProjectiveSpace 2;                 |
+-------------------------------------------------+
|i3 : phi = map(Y, X, matrix{{0,-1},{1,0}});      |
|                                                 |
|o3 : ToricMap Y <--- X                           |
+-------------------------------------------------+
|i4 : D = {0,3,0,0};                              |
+-------------------------------------------------+
|i5 : prune HDI(phi, 1, D)                        |
|                                                 |
|o5 = cokernel {1} | x_2 x_0  0   |               |
|              {1} | 0   -x_2 x_0 |               |
|                                                 |
|                                                2|
|o5 : QQ[x ..x ]-module, quotient of (QQ[x ..x ]) |
|         0   2                           0   2   |
+-------------------------------------------------+

2) When $\varphi \colon Y \rightarrow Y$ is a toric Frobenius map, i.e. induced
from the natural morphism on the dense torus given by raising all of the
coordinates to the same power, then the method \texttt{frobeniusPushforward}
allows one to compute pushforwards of any coherent sheaf. For instance, the
pushforward of the trivial bundle on $\mathbb{P}^2$ by the second Frobenius map
splits into 4 line bundles.

+----------------------------------------+
|i6 : S = ring Y;                        |
+----------------------------------------+
|i7 : frobeniusPushforward(2,S^1)        |
|                                        |
|      4                                 |
|o7 = S                                  |
|                                        |
|o7 : S-module, free, degrees {0..1, 2:1}|
+----------------------------------------+

Contributors
============

The following people have generously contributed code, improved existing code,
or enhanced the documentation: Mahrud Sayrafi (see
https://www-users.cse.umn.edu/~mahrud/ ), and Gregory G. Smith (see
https://mast.queensu.ca/~ggsmith/ ).

References
==========

M. Roth and S. Zotine, \textit{Reduced \v{C}ech complexes and computing higher
direct images under toric maps}, to appear on arXiv

Caveat
======

In case 1), we have only implemented the computation for line bundles, and if
the target is simplicial. The only finite maps for which the pushforward is
implemented are the Frobenius maps.

Author
======

  * Sasha Zotine (see https://sites.google.com/view/szotine/home )
    <zotinea@mcmaster.ca>

Version
=======

This documentation describes version 1.1 of ToricHigherDirectImages, released
2026 April.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{ToricHigherDirectImagesSource,                                         |
|  title = {{ToricHigherDirectImages: computations involving pushforwards and |
|  author = {Sasha Zotine},                                                   |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|-----------------------------------------------------------------------------|
|higher direct images of toric maps. Version~1.1}},                           |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * allNefContractions -- produces all
        contractions corresponding to each face in the nef cone
      * computeEigencharacters -- compute the
        eigencharacters
      * frobeniusPushforward -- compute the
        pushforward of a module under the $p$th toric Frobenius map
      * HDI -- compute the $i$th higher direct image
      * nefContraction -- produce a contraction from a
        vector in the nef cone
      * nefRayContractions -- produces all
        contractions corresponding to rays in the nef cone
  * Methods
      * "allNefContractions(NormalToricVariety)" -- see
        allNefContractions, -- produces all contractions
        corresponding to each face in the nef cone
      * "computeEigencharacters(ToricMap,ZZ,List)" -- see
        computeEigencharacters, -- compute the
        eigencharacters
      * "computeEigencharacters(ToricMap,ZZ,ToricDivisor)" -- see
        computeEigencharacters, -- compute the
        eigencharacters
      * "frobeniusPushforward(ZZ,Complex)" -- see frobeniusPushforward,
        -- compute the pushforward of a module under the
        $p$th toric Frobenius map
      * "frobeniusPushforward(ZZ,Matrix)" -- see frobeniusPushforward,
        -- compute the pushforward of a module under the
        $p$th toric Frobenius map
      * "frobeniusPushforward(ZZ,Module)" -- see frobeniusPushforward,
        -- compute the pushforward of a module under the
        $p$th toric Frobenius map
      * "HDI(ToricMap,ZZ,CoherentSheaf)" -- see HDI, -- compute the
        $i$th higher direct image
      * "HDI(ToricMap,ZZ,List)" -- see HDI, -- compute the $i$th
        higher direct image
      * "HDI(ToricMap,ZZ,Module)" -- see HDI, -- compute the $i$th
        higher direct image
      * "HDI(ToricMap,ZZ,ToricDivisor)" -- see HDI, -- compute the
        $i$th higher direct image
      * "ToricMap _*" -- see HDI, -- compute the $i$th higher direct
        image
      * "nefContraction(NormalToricVariety,List)" -- see nefContraction,
        -- produce a contraction from a vector in the nef cone
      * "nefContraction(NormalToricVariety,Matrix)" -- see
        nefContraction, -- produce a contraction from a vector
        in the nef cone
      * "nefContraction(NormalToricVariety,Vector)" -- see
        nefContraction, -- produce a contraction from a vector
        in the nef cone
      * "nefRayContractions(NormalToricVariety)" -- see
        nefRayContractions, -- produces all contractions
        corresponding to rays in the nef cone

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

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

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

The source of this document is in ToricHigherDirectImages.m2:579:0.

allNefContractions -- produces all contractions corresponding to each face in the nef cone
******************************************************************************************

  * Usage:
        nefRayContractions X
  * Inputs:
      * X, a normal toric variety (NormalToricVarieties),
  * Outputs:
      * a list (Macaulay2Doc), of ToricMaps obtained by contracting
        a face of the nef cone

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

This method chooses a vector in the relative interior of every face of the nef
cone and produces the corresponding map.

+---------------------------------------------+
|i1 : X = hirzebruchSurface 1;                |
+---------------------------------------------+
|i2 : L = allNefContractions X                |
|                                             |
|o2 = {| 1 0 |, | 1 0 |, | 1 0 |}             |
|               | 0 1 |  | 0 1 |              |
|                                             |
|o2 : List                                    |
+---------------------------------------------+
|i3 : assert(all(L, phi -> isWellDefined phi))|
+---------------------------------------------+

Caveat
======

This method is exponential in the number of rays of the fan, so the runtime may
be quite long!

See also
========

  * nefContraction(NormalToricVariety,List) -- produce a
    contraction from a vector in the nef cone
  * nefContraction(NormalToricVariety,Vector) -- produce
    a contraction from a vector in the nef cone
  * nefContraction(NormalToricVariety,Matrix) -- produce
    a contraction from a vector in the nef cone
  * nefRayContractions(NormalToricVariety), --
    produces all contractions corresponding to rays in the nef cone

Ways to use allNefContractions:
===============================

  * "allNefContractions(NormalToricVariety)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:763:0.

computeEigencharacters -- compute the eigencharacters
*****************************************************

  * Usage:
        computeEigencharacters(phi, i, D)
  * Inputs:
      * phi, a toric map (NormalToricVarieties), a surjective
        toric morphism
      * i, an integer (Macaulay2Doc),
      * D, a list (Macaulay2Doc), or a toric divisor (NormalToricVarieties),
        a list indexing a Cartier divisor
        on the source of phi
  * Outputs:
      * a hash table (Macaulay2Doc), whose keys are the
        eigencharacters and values are the (D,E) pairs

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

This method is the implementation of Algorithm A.5 in "Reduced \v{C}ech
complexes and computing higher direct images under toric maps". More precisely,
the higher direct image sheaf inherits a trivial torus action by the kernel
torus $T_K :\!= \ker \phi\vert_{T_X}$, and so splits into a direct sum of
sheaves indexed by eigencharacters. This method computes these characters, as
well as a pair of divisors $(D,E)$ for use in Algorithm A.8 which computes the
higher direct image sheaf.

+----------------------------------------+
|i1 : X = hirzebruchSurface 1;           |
+----------------------------------------+
|i2 : Y = toricProjectiveSpace 1;        |
+----------------------------------------+
|i3 : phi = map(Y,X,matrix{{1,0}});      |
|                                        |
|o3 : ToricMap Y <--- X                  |
+----------------------------------------+
|i4 : D = {0,-3,0,0};                    |
+----------------------------------------+
|i5 : computeEigencharacters(phi,1,D)    |
|                                        |
|o5 = HashTable{| 0 | => (| 0  |, {{1}})}|
|               | 1 |     | -2 |         |
|                         | 0  |         |
|                         | -1 |         |
|               | 0 | => (| 0  |, {{2}}) |
|               | 2 |     | -1 |         |
|                         | 0  |         |
|                         | -2 |         |
|                                        |
|o5 : HashTable                          |
+----------------------------------------+

One might hope that the set of eigencharacters is a convex set, but this is not
always the case. For instance, when $X$ is the blowup of $\mathbb{P}^1 \times
\mathbb{P}^1$ at the four torus fixed points and phi is the projection to
$\mathbb{P}^1$, we can find an example of a line bundle whose eigencharacters
are not convex.

+---------------------------------------------------------------------------+
|i6 : Z = normalToricVariety({{1,0},{1,1},{0,1},{-1,1},{-1,0},{-1,-1},      |
|         {0,-1},{1,-1}},{{0,1},{1,2},{2,3},{3,4},{4,5},{5,6},{6,7},{0,7}});|
+---------------------------------------------------------------------------+
|i7 : phi = map(Y,Z,matrix{{1,0}});                                         |
|                                                                           |
|o7 : ToricMap Y <--- Z                                                     |
+---------------------------------------------------------------------------+
|i8 : D = toricDivisor({0,-2,0,0,0,-2,1,0},Z);                              |
|                                                                           |
|o8 : ToricDivisor on Z                                                     |
+---------------------------------------------------------------------------+
|i9 : keys computeEigencharacters(phi,1,D)                                  |
|                                                                           |
|o9 = {| 0  |, | 0 |}                                                       |
|      | -1 |  | 1 |                                                        |
|                                                                           |
|o9 : List                                                                  |
+---------------------------------------------------------------------------+

See also
========

  * HDI(ToricMap,ZZ,List) -- compute the $i$th higher direct image
  * HDI(ToricMap,ZZ,ToricDivisor) -- compute the $i$th higher
    direct image
  * HDI(ToricMap,ZZ,Module) -- compute the $i$th higher direct
    image
  * HDI(ToricMap,ZZ,CoherentSheaf) -- compute the $i$th higher
    direct image

Ways to use computeEigencharacters:
===================================

  * "computeEigencharacters(ToricMap,ZZ,List)"
  * "computeEigencharacters(ToricMap,ZZ,ToricDivisor)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:816:0.

frobeniusPushforward -- compute the pushforward of a module under the $p$th toric Frobenius map
***********************************************************************************************

  * Usage:
        frobeniusPushforward(p, M)
        frobeniusPushforward_p M
  * Inputs:
      * p, an integer (Macaulay2Doc),
      * M, a module (Macaulay2Doc), a matrix (Macaulay2Doc),
        or a complex (Complexes),
  * Outputs:
      * a module (Macaulay2Doc), a matrix (Macaulay2Doc),
        or a complex (Complexes), which
        is the pushforward of M under the $p$th toric Frobenius.

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

The $p$th toric Frobenius is a toric morphism $F_p \colon X \rightarrow X$
which is the extension of the natural group homomorphism $T_X \rightarrow T_X$
given by raising all coordinates to the $p$th power. This allows one to view
the Cox ring $R$ of $X$ as a module over itself, with the module action being
$r \cdot m :\!= r^p m$. The extension of this action to modules also allows one
to compute the pushforward by $F_p$. Note that $p$ need not be prime, nor
related to the characteristic of the ground field in any way. Here is the 4th
pushforward of the Cox ring of the first Hirzebruch surface.

+-----------------------------------------------------------------------------+
|i1 : X = hirzebruchSurface 1;                                                |
+-----------------------------------------------------------------------------+
|i2 : R = ring X;                                                             |
+-----------------------------------------------------------------------------+
|i3 : frobeniusPushforward(4, R^1)                                            |
|                                                                             |
|      16                                                                     |
|o3 = R                                                                       |
|                                                                             |
|o3 : R-module, free, degrees {{0, 0}, 3:{0, 1}, {1, 0}, 3:{0, 1}, {1, 0}, {1,|
|-----------------------------------------------------------------------------|
|1}, 2:{0, 1}, {1, 0}, 2:{1, 1}, {0, 1}}                                      |
+-----------------------------------------------------------------------------+

We can pushforward many kinds of modules. Here is the pushforward of an ideal.

+-------------------------------------+
|i4 : I = module ideal {R_0, R_2};    |
+-------------------------------------+
|i5 : prune frobeniusPushforward(2, I)|
|                                     |
|o5 = cokernel {1, 0} | -x_2 |        |
|              {0, 1} | 0    |        |
|              {1, 0} | 0    |        |
|              {1, 0} | x_0  |        |
|              {0, 1} | 0    |        |
|                                     |
|                            5        |
|o5 : R-module, quotient of R         |
+-------------------------------------+

Here is the pushforward of a free module.

+-----------------------------------------------------------------------------+
|i6 : F = R^{{1,0},{0,1}};                                                    |
+-----------------------------------------------------------------------------+
|i7 : frobeniusPushforward(2, F)                                              |
|                                                                             |
|      8                                                                      |
|o7 = R                                                                       |
|                                                                             |
|o7 : R-module, free, degrees {{0, 0}, {0, 1}, {0, 0}, {-1, 1}, 2:{0, 0}, {1, |
|-----------------------------------------------------------------------------|
|0}, {0, 0}}                                                                  |
+-----------------------------------------------------------------------------+

Here is the pushforward of a torsion module.

+-------------------------------------+
|i8 : M = R^1/(module I)              |
|                                     |
|o8 = cokernel | x_0 x_2 |            |
|                                     |
|                            1        |
|o8 : R-module, quotient of R         |
+-------------------------------------+
|i9 : prune frobeniusPushforward(2, M)|
|                                     |
|o9 = cokernel | x_2 x_0 |            |
|                                     |
|                            1        |
|o9 : R-module, quotient of R         |
+-------------------------------------+

As mentioned, $p$ is not related to the characteristic of the field, and the
outputs will be the same modules over a different coefficient ring.

+--------------------------------------------------------+
|i10 : Y = hirzebruchSurface(1, CoefficientRing => ZZ/2);|
+--------------------------------------------------------+
|i11 : S = ring Y;                                       |
+--------------------------------------------------------+
|i12 : I' = module ideal {S_0, S_2};                     |
+--------------------------------------------------------+
|i13 : prune frobeniusPushforward(2, I')                 |
|                                                        |
|o13 = cokernel {1, 0} | x_2 |                           |
|               {0, 1} | 0   |                           |
|               {1, 0} | 0   |                           |
|               {1, 0} | x_0 |                           |
|               {0, 1} | 0   |                           |
|                                                        |
|                             5                          |
|o13 : S-module, quotient of S                           |
+--------------------------------------------------------+

The pushforward is an endofunctor on the category of $R$-modules, so we may
apply it to morphisms and complexes of $R$-modules.

+---------------------------------------+
|i14 : X = hirzebruchSurface 1;         |
+---------------------------------------+
|i15 : R = ring X;                      |
+---------------------------------------+
|i16 : C = complex koszul vars R        |
|                                       |
|       1      4      6      4      1   |
|o16 = R  <-- R  <-- R  <-- R  <-- R    |
|                                       |
|      0      1      2      3      4    |
|                                       |
|o16 : Complex                          |
+---------------------------------------+
|i17 : frobeniusPushforward_2 C         |
|                                       |
|       4      16      24      16      4|
|o17 = R  <-- R   <-- R   <-- R   <-- R |
|                                       |
|      0      1       2       3       4 |
|                                       |
|o17 : Complex                          |
+---------------------------------------+

See also
========

  * HDI(ToricMap,ZZ,List) -- compute the $i$th higher direct image
  * HDI(ToricMap,ZZ,ToricDivisor) -- compute the $i$th higher
    direct image
  * HDI(ToricMap,ZZ,Module) -- compute the $i$th higher direct
    image
  * HDI(ToricMap,ZZ,CoherentSheaf) -- compute the $i$th higher
    direct image

Ways to use frobeniusPushforward:
=================================

  * "frobeniusPushforward(ZZ,Complex)"
  * "frobeniusPushforward(ZZ,Matrix)"
  * "frobeniusPushforward(ZZ,Module)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:648:0.

HDI -- compute the $i$th higher direct image
********************************************

  * Usage:
        HDI(phi, i, D)
        phi_*^i D
  * Inputs:
      * phi, a toric map (NormalToricVarieties), a surjective
        toric morphism
      * i, an integer (Macaulay2Doc),
      * D, a list (Macaulay2Doc), a toric divisor (NormalToricVarieties),
        a module (Macaulay2Doc),
        or a coherent sheaf (Varieties),
        a Cartier divisor or rank one free module or
        line bundle on the source of phi.
  * Outputs:
      * a module (Macaulay2Doc), or a coherent sheaf (Varieties),
        which is the $i$th higher direct image of
        $\mathcal{O}_X(D)$.

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

This method implements Algorithm A.8 in "Reduced \v{C}ech complexes and
computing higher direct images under toric maps".

The first Hirzebruch surface $\mathbb{F}_1$ has two geometric interpretations:
1) as the projective bundle $\mathbb{P}(\mathcal{O}_{\mathbb{P}^1} \oplus
\mathcal{O}_{\mathbb{P}^1})$ or as the blowup of $\mathbb{P}^2$ at a
torus-fixed point. In both cases we get a toric morphism, the projection and
blowdown map. In the first case, the (higher) direct images of a line bundle
are themselves vector bundles, and hence split.

+------------------------------------------------+
|i1 : X = hirzebruchSurface 1;                   |
+------------------------------------------------+
|i2 : Y = toricProjectiveSpace(1, Variable => y);|
+------------------------------------------------+
|i3 : phi = map(Y, X, matrix {{1,0}});           |
|                                                |
|o3 : ToricMap Y <--- X                          |
+------------------------------------------------+
|i4 : D1 = {3,4,0,0};                            |
+------------------------------------------------+
|i5 : RD1 = prune HDI(phi,0,D1)                  |
|                                                |
|                 5                              |
|o5 = (QQ[y ..y ])                               |
|          0   1                                 |
|                                                |
|o5 : QQ[y ..y ]-module, free, degrees {-3..1}   |
|         0   1                                  |
+------------------------------------------------+
|i6 : D2 = toricDivisor({3,-4,0,0},X);           |
|                                                |
|o6 : ToricDivisor on X                          |
+------------------------------------------------+
|i7 : RD2 = prune HDI(phi,1,D2)                  |
|                                                |
|                 3                              |
|o7 = (QQ[y ..y ])                               |
|          0   1                                 |
|                                                |
|o7 : QQ[y ..y ]-module, free, degrees {-6..-4}  |
|         0   1                                  |
+------------------------------------------------+

In the second case, we can find line bundles whose (higher) direct images which
have relations or torsion.

+---------------------------------------------------+
|i8 : Z = toricProjectiveSpace(2, Variable => z);   |
+---------------------------------------------------+
|i9 : phi = map(Z, X, matrix {{0,-1},{1,0}});       |
|                                                   |
|o9 : ToricMap Z <--- X                             |
+---------------------------------------------------+
|i10 : M = (ring X)^{{-6,3}};                       |
+---------------------------------------------------+
|i11 : RM = prune phi_*^0 M                         |
|                                                   |
|                  1                                |
|o11 = (QQ[z ..z ])                                 |
|           0   2                                   |
|                                                   |
|o11 : QQ[z ..z ]-module, free, degrees {3}         |
|          0   2                                    |
+---------------------------------------------------+
|i12 : L = sheaf_X M;                               |
+---------------------------------------------------+
|i13 : RL = prune phi_*^1 L                         |
|                                                   |
|o13 = cokernel {-8} | z_2 z_0  0    0    0    0   ||
|               {-8} | 0   -z_2 z_0  0    0    0   ||
|               {-8} | 0   0    -z_2 z_0  0    0   ||
|               {-8} | 0   0    0    -z_2 z_0  0   ||
|               {-8} | 0   0    0    0    -z_2 z_0 ||
|                                                   |
|                                          5        |
|o13 : coherent sheaf on Z, quotient of OO  (8)     |
|                                         Z         |
+---------------------------------------------------+
|i14 : annihilator RL                               |
|                                                   |
|              5     4   2 3   3 2   4     5        |
|o14 = ideal (z , z z , z z , z z , z z , z )       |
|              2   0 2   0 2   0 2   0 2   0        |
|                                                   |
|o14 : Ideal of QQ[z ..z ]                          |
|                   0   2                           |
+---------------------------------------------------+

See also
========

  * frobeniusPushforward(ZZ,Module) -- compute the
    pushforward of a module under the $p$th toric Frobenius map
  * frobeniusPushforward(ZZ,Matrix) -- compute the
    pushforward of a module under the $p$th toric Frobenius map
  * frobeniusPushforward(ZZ,Complex) -- compute
    the pushforward of a module under the $p$th toric Frobenius map

Ways to use HDI:
================

  * "HDI(ToricMap,ZZ,CoherentSheaf)"
  * "HDI(ToricMap,ZZ,List)"
  * "HDI(ToricMap,ZZ,Module)"
  * "HDI(ToricMap,ZZ,ToricDivisor)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:872:0.

nefContraction -- produce a contraction from a vector in the nef cone
*********************************************************************

  * Usage:
        nefContraction(X, v)
  * Inputs:
      * X, a normal toric variety (NormalToricVarieties),
      * v, a list (Macaulay2Doc), a vector (Macaulay2Doc),
        or a matrix (Macaulay2Doc), a
        vector presumed to be in the nef cone of $X$
  * Outputs:
      * a toric map (NormalToricVarieties),

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

A vector in the nef cone of a toric variety determines an embedding of the
toric variety via GIT quotients. When the vector lies on the boundary of the
nef cone, the resulting embedding is typically a "smaller" toric variety on
which the original variety can surject. These types of maps are commonly used
in the minimal model program (MMP)

More precisely, see Lemma 14.4.6 and Theorem 15.1.10 in
HREF("https://dacox.people.amherst.edu/toric.html", "Toric varieties"). The nef
cone of a toric variety is a GKZ chamber and each face of this cone is also a
GKZ chamber, hence the nef cone of another toric variety. Since both of these
are GIT quotients, there is a natural map induced by the projection of vector
spaces between the quotients, which this method produces.

The first Hirzebruch surface $\mathbb{F}_1$ comes with two natural maps to
$\mathbb{P}^1$ (projection to the base) and $\mathbb{P}^2$ (the blowdown map).
Both of these can be realized as maps obtained from the MMP.

+-----------------------------------------------------------------------------+
|i1 : X = hirzebruchSurface 1;                                                |
+-----------------------------------------------------------------------------+
|i2 : pi1 = nefContraction(X, vector {1,0})                                   |
|                                                                             |
|o2 = | 1 0 |                                                                 |
|                                                                             |
|o2 : ToricMap normalToricVariety ({{1}, {-1}}, {{0}, {1}}) <--- X            |
+-----------------------------------------------------------------------------+
|i3 : assert(isWellDefined pi1);                                              |
+-----------------------------------------------------------------------------+
|i4 : assert(isProjective target pi1 and dim target pi1 == 1);                |
+-----------------------------------------------------------------------------+
|i5 : pi2 = nefContraction(X, matrix {{0},{1}})                               |
|                                                                             |
|o5 = | 1 0 |                                                                 |
|     | 0 1 |                                                                 |
|                                                                             |
|o5 : ToricMap normalToricVariety ({{1, 0}, {-1, 1}, {0, -1}}, {{0, 1}, {0,   |
|-----------------------------------------------------------------------------|
|2}, {1, 2}}) <--- X                                                          |
+-----------------------------------------------------------------------------+
|i6 : assert(isProjective target pi1 and dim target pi2 == 2);                |
+-----------------------------------------------------------------------------+
|i7 : assert(rank picardGroup target pi2 == 1);                               |
+-----------------------------------------------------------------------------+

If the vector is in the interior of the nef cone, then the resulting toric
variety is the same as the original, and so the resulting surjection is just
the identity.

+-----------------------------------------------------------------------------+
|i8 : idty = nefContraction(X,{1,1})                                          |
|                                                                             |
|o8 = | 1 0 |                                                                 |
|     | 0 1 |                                                                 |
|                                                                             |
|o8 : ToricMap normalToricVariety ({{1, 0}, {0, 1}, {-1, 1}, {0, -1}}, {{0,   |
|-----------------------------------------------------------------------------|
|1}, {0, 3}, {1, 2}, {2, 3}}) <--- X                                          |
+-----------------------------------------------------------------------------+
|i9 : assert(rays target idty == rays X);                                     |
+-----------------------------------------------------------------------------+
|i10 : assert(max target idty == max X);                                      |
+-----------------------------------------------------------------------------+

See also
========

  * nefRayContractions(NormalToricVariety), --
    produces all contractions corresponding to rays in the nef cone
  * allNefContractions(NormalToricVariety), --
    produces all contractions corresponding to each face in the nef cone

Ways to use nefContraction:
===========================

  * "nefContraction(NormalToricVariety,List)"
  * "nefContraction(NormalToricVariety,Matrix)"
  * "nefContraction(NormalToricVariety,Vector)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:701:0.

nefRayContractions -- produces all contractions corresponding to rays in the nef cone
*************************************************************************************

  * Usage:
        nefRayContractions X
  * Inputs:
      * X, a normal toric variety (NormalToricVarieties),
  * Outputs:
      * a list (Macaulay2Doc), of ToricMaps obtained by each ray of
        the nef cone

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

This method is a convenient way to produce all of the nef contractions
corresponding to the rays of the nef cone, without the user needing to know
those rays.

+-------------------------------------------------------------+
|i1 : X = hirzebruchSurface 1;                                |
+-------------------------------------------------------------+
|i2 : L = nefRayContractions X                                |
|                                                             |
|o2 = {| 1 0 |, | 1 0 |}                                      |
|               | 0 1 |                                       |
|                                                             |
|o2 : List                                                    |
+-------------------------------------------------------------+
|i3 : assert(isProjective target L_0 and dim target L_0 == 1);|
+-------------------------------------------------------------+
|i4 : assert(isProjective target L_1 and dim target L_1 == 2);|
+-------------------------------------------------------------+
|i5 : assert(rank picardGroup target L_1 == 1);               |
+-------------------------------------------------------------+

See also
========

  * nefContraction(NormalToricVariety,List) -- produce a
    contraction from a vector in the nef cone
  * nefContraction(NormalToricVariety,Vector) -- produce
    a contraction from a vector in the nef cone
  * nefContraction(NormalToricVariety,Matrix) -- produce
    a contraction from a vector in the nef cone
  * nefRayContractions(NormalToricVariety), --
    produces all contractions corresponding to rays in the nef cone

Ways to use nefRayContractions:
===============================

  * "nefRayContractions(NormalToricVariety)"

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

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

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

The source of this document is in ToricHigherDirectImages.m2:732:0.