This is Truncations.info, produced by Macaulay2, version 1.21

Truncations -- truncations of graded ring, ideals and modules
*************************************************************

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

This package provides methods for truncation of a graded ring, or a graded
module or ideal over a graded ring (see truncate(List,Module)).
Truncation is functorial: it can be applied to
maps of modules as well, and the truncation of a composition of maps is the
composition of the truncations (see truncate(List,Matrix)).

Let $S$ be a $\ZZ^r$-graded ring whose variables have non-negative degrees and
$M$ be a graded $S$-module. Then for a finite subset of degrees $L\subset\ZZ^r$
the method truncate(L, M) computes $$M_{\ge L} = \bigoplus_{m\in L+\NN^r}
M_m,$$ where the sum is taken over all degrees $m \in \ZZ^r$ which are
component-wise greater than or equal to some degree $d\in L$. In this case the
truncation is a submodule of $M$.

+--------------------------------------------+
|i1 : R = ZZ/101[a..d, Degrees => {1,2,3,4}];|
+--------------------------------------------+
|i2 : truncate(4, ideal"a3,b3")              |
|                                            |
|             4   3    3    3   3            |
|o2 = ideal (a , a b, a c, b , a d)          |
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+

More generally, let $S$ be the total coordinate ring of a simplicial toric
variety $X$ with Picard group $\operatorname{Pic} X$. Then for a finite subset
$L\subset\operatorname{Pic} X$, the truncation $F_{\ge L}$ of a free module $F$
may be defined as the submodule generated by $$F_{\ge L} = \bigoplus_{m\in
L+\operatorname{Nef} X} F_m,$$ where $\operatorname{Nef} X$ is the semigroup of
nef line bundles in $\operatorname{Pic} X$ (c.f. Definition 5.1 in [MS04]).
Then for a graded $S$-module $M$ with presentation (Macaulay2Doc),
$0 \gets M \gets G \gets H,$ where $G$ and $H$ are
free modules, the truncation $M_{\ge L}$ is the $S$-module with presentation
$$0 \gets M_{\ge L} \gets G_{\ge L} \gets H_{\ge L}.$$ Note that $M_{\ge L}$ is
not a submodule of $M$ in general, but exact sequences are preserved and since
$M/M_{\ge L}$ is annihilated by a power of the irrelevant ideal of $S$, a
module and its truncation define the same sheaf.

+---------------------------------------------------+
|i3 : needsPackage "NormalToricVarieties";          |
+---------------------------------------------------+
|i4 : dP6 = smoothFanoToricVariety(2, 4);           |
+---------------------------------------------------+
|i5 : S = ring dP6;                                 |
+---------------------------------------------------+
|i6 : M = S^{-{0,0,1,0}};                           |
+---------------------------------------------------+
|i7 : N = truncate({0,0,0,0}, M)                    |
|                                                   |
|o7 = image {0, 0, 1, 0} | x_4 x_2 |                |
|                                                   |
|                             1                     |
|o7 : S-module, submodule of S                      |
+---------------------------------------------------+
|i8 : N == coker truncate({0,0,0,0}, presentation M)|
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+

For the most general case, if $S$ is a $\ZZ^r$-graded ring where the degree
components of variables may be negative, the result is the same as the above
but we fix the nef cone to be the positive orthant $\NN^r$.

+---------------------------------------------------------+
|i9 : R = ZZ/101[a..d, Degrees => {2:{1,0},{0,1},{-3,1}}];|
+---------------------------------------------------------+
|i10 : M = R^1/ideal d                                    |
|                                                         |
|o10 = cokernel | d |                                     |
|                                                         |
|                             1                           |
|o10 : R-module, quotient of R                            |
+---------------------------------------------------------+
|i11 : N = truncate({0,0}, M)                             |
|                                                         |
|o11 = cokernel | b3d ab2d a2bd a3d |                     |
|                                                         |
|                             1                           |
|o11 : R-module, quotient of R                            |
+---------------------------------------------------------+
|i12 : isSubset(M, N)                                     |
|                                                         |
|o12 = false                                              |
+---------------------------------------------------------+

The polyhedral algorithms implemented in this package correctly handle many
cases. The behavior of truncate (Macaulay2Doc), changed as of
Macaulay2 version 1.13 to support exterior algebras (Macaulay2Doc),
and again in Macaulay2 version 1.19 to
support Cox rings of simplicial normal toric varieties (NormalToricVarieties).

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

Lauren Cranton Heller contributed to the code and documentation for this
package.

References
==========

  * [MS04]: Maclagan and Smith, Multigraded Castelnuovo-Mumford Regularity (see
    arXiv:math/0305214 (see https://arxiv.org/abs/math/0305214 )).

See also
========

  * basis (Macaulay2Doc) -- basis or generating set of all or part
    of a ring, ideal or module

Authors
=======

  * David Eisenbud (see https://www.msri.org/~de ) <de@msri.org>
  * Mike Stillman (see https://www.math.cornell.edu/~mike )
    <mike@math.cornell.edu>
  * Mahrud Sayrafi (see https://math.umn.edu/~mahrud ) <mahrud@umn.edu>

Version
=======

This documentation describes version 1.0 of Truncations.

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

The source code from which this documentation is derived is in the file
Truncations.m2 (see common/share/Macaulay2/Truncations.m2 ). The auxiliary
files accompanying it are in the directory Truncations/ (see
common/share/Macaulay2/Truncations/ ).

Exports
=======

  * Methods
      * truncate(List,Matrix) -- truncation
        of a map of free modules
      * "truncate(ZZ,Matrix)" -- see truncate(List,Matrix),
        -- truncation of a map of free modules
      * "truncate(List,Ideal)" -- see truncate(List,Module),
        -- truncation of the graded ring, ideal or
        module at a specified degree or set of degrees
      * truncate(List,Module) -- truncation
        of the graded ring, ideal or module at a specified degree or set of
        degrees
      * "truncate(List,Ring)" -- see truncate(List,Module),
        -- truncation of the graded ring, ideal or
        module at a specified degree or set of degrees
      * "truncate(ZZ,Ideal)" -- see truncate(List,Module),
        -- truncation of the graded ring, ideal or
        module at a specified degree or set of degrees
      * "truncate(ZZ,Module)" -- see truncate(List,Module),
        -- truncation of the graded ring, ideal or
        module at a specified degree or set of degrees
      * "truncate(ZZ,Ring)" -- see truncate(List,Module),
        -- truncation of the graded ring, ideal or
        module at a specified degree or set of degrees

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

The object Truncations, is a package (Macaulay2Doc).

truncate(List,Module) -- truncation of the graded ring, ideal or module at a specified degree or set of degrees
***************************************************************************************************************

Synopsis
========

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate(degs, M)
  * Inputs:
      * degs, a list (Macaulay2Doc), an integer (Macaulay2Doc),
        or a list (Macaulay2Doc), a single
        degree, a multidegree, or a list of degrees or multidegrees
      * M, a module (Macaulay2Doc), a module (Macaulay2Doc),
        an ideal (Macaulay2Doc), or a
        ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, indicates whether the result should be
        trimmed (Macaulay2Doc),
  * Outputs:
      * a module (Macaulay2Doc), a module (Macaulay2Doc),
        or an ideal (Macaulay2Doc), the
        truncation submodule $M_{\ge degs}$

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

The truncation to degree $d$ in the singly graded case of a module (or ring or
ideal) is generated by all homogeneous elements of degree at least $d$ in $M$.
The resulting truncation is minimally generated (assuming that $M$ is graded).

+--------------------------------------+
|i1 : R = ZZ/101[a..c];                |
+--------------------------------------+
|i2 : truncate(2, R)                   |
|                                      |
|             2             2        2 |
|o2 = ideal (c , b*c, a*c, b , a*b, a )|
|                                      |
|o2 : Ideal of R                       |
+--------------------------------------+
|i3 : truncate(2, R^1)                 |
|                                      |
|o3 = image | c2 bc ac b2 ab a2 |      |
|                                      |
|                             1        |
|o3 : R-module, submodule of R         |
+--------------------------------------+
|i4 : truncate(2, R^{0,-3})            |
|                                      |
|o4 = image {0} | c2 bc ac b2 ab a2 0 ||
|           {3} | 0  0  0  0  0  0  1 ||
|                                      |
|                             2        |
|o4 : R-module, submodule of R         |
+--------------------------------------+

The coefficient ring of $R$ may be $\ZZ$ or another polynomial ring. Over
$\ZZ$, the generators may not be minimal, but they do generate.

+--------------------------------------------+
|i5 : A = ZZ[x,y,z];                         |
+--------------------------------------------+
|i6 : truncate(2, ideal(3*x, 5*y, 15))       |
|                                            |
|               2                2         2 |
|o6 = ideal (15z , 5y*z, 3x*z, 5y , x*y, 3x )|
|                                            |
|o6 : Ideal of A                             |
+--------------------------------------------+

If a multi-degree $d$ is given, then the result is the submodule generated by
elements of degree $d+\NN\mathcal C$ where $\mathcal C$ is either a generating
set for the degree semigroup of $R$ or the Nef cone of the toric variety.

The following example finds the 11 generators needed to obtain all graded
elements whose degrees are at least $\{7,24\}$.

+-----------------------------------------------------------------------------+
|i7 : S = ZZ/101[x,y,z, Degrees => {{1,3},{1,4},{1,0}}];                      |
+-----------------------------------------------------------------------------+
|i8 : trunc = truncate({7,24}, S^1 ++ S^{{-8,-20}})                           |
|                                                                             |
|o8 = image {0, 0}  | y6z y7 xy6 x2y5 x3y4 x4y3 x6y2 x7y x8 0 0  |            |
|           {8, 20} | 0   0  0   0    0    0    0    0   0  y x2 |            |
|                                                                             |
|                             2                                               |
|o8 : S-module, submodule of S                                                |
+-----------------------------------------------------------------------------+
|i9 : degrees trunc                                                           |
|                                                                             |
|o9 = {{7, 24}, {7, 28}, {7, 27}, {7, 26}, {7, 25}, {7, 24}, {8, 26}, {8, 25},|
|     ------------------------------------------------------------------------|
|     {8, 24}, {9, 24}, {10, 26}}                                             |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

Given a list of multi-degrees $D$, then the result is the submodule generated
by elements of degree $d+\NN\mathcal C$ for any $d\in D$.

The following example finds the generators needed to obtain all graded elements
whose degrees at least $\{3,0\}$ or at least $\{0,1\}$. The resulting module is
also minimally generated.

+-----------------------------------------------------------------------------+
|i10 : S = ZZ/101[x,y,z, Degrees => {{1,3},{1,4},{1,0}}];                     |
+-----------------------------------------------------------------------------+
|i11 : trunc = truncate({{3,0}, {0,1}}, S^1 ++ S^{{-8,-20}})                  |
|                                                                             |
|o11 = image {0, 0}  | y x z3 yz2 xz2 y2z xyz x2z y3 xy2 x2y x3 0 |           |
|            {8, 20} | 0 0 0  0   0   0   0   0   0  0   0   0  1 |           |
|                                                                             |
|                              2                                              |
|o11 : S-module, submodule of S                                               |
+-----------------------------------------------------------------------------+
|i12 : degrees trunc                                                          |
|                                                                             |
|o12 = {{1, 4}, {1, 3}, {3, 0}, {3, 4}, {3, 3}, {3, 8}, {3, 7}, {3, 6}, {3,   |
|      -----------------------------------------------------------------------|
|      12}, {3, 11}, {3, 10}, {3, 9}, {8, 20}}                                |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+

The coefficient ring may also be a polynomial ring. In this example, the
coefficient variables also have degree one. The given generators will generate
the truncation over the coefficient ring.

+-----------------------------------------------------------------------------+
|i13 : B = R[x,y,z, Join => false];                                           |
+-----------------------------------------------------------------------------+
|i14 : degrees B                                                              |
|                                                                             |
|o14 = {{1}, {1}, {1}}                                                        |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : truncate(2, B^1)                                                       |
|                                                                             |
|o15 = image | c2 bc ac b2 ab a2 cz bz az cy by ay cx bx ax z2 yz xz y2 xy x2 |
|                                                                             |
|                              1                                              |
|o15 : B-module, submodule of B                                               |
|-----------------------------------------------------------------------------|
||                                                                            |
+-----------------------------------------------------------------------------+
|i16 : truncate(4, ideal(b^2*y,x^3))                                          |
|                                                                             |
|              2      3      2    2      2 2   2        3     3     3   3     |
|o16 = ideal (b c*y, b y, a*b y, b y*z, b y , b x*y, c*x , b*x , a*x , x z,   |
|      -----------------------------------------------------------------------|
|       3    4                                                                |
|      x y, x )                                                               |
|                                                                             |
|o16 : Ideal of B                                                             |
+-----------------------------------------------------------------------------+

If the coefficient variables have degree 0:

+--------------------------------------------+
|i17 : A1 = ZZ/101[a,b,c, Degrees => {3:{}}];|
+--------------------------------------------+
|i18 : degrees A1                            |
|                                            |
|o18 = {{}, {}, {}}                          |
|                                            |
|o18 : List                                  |
+--------------------------------------------+
|i19 : B1 = A1[x,y];                         |
+--------------------------------------------+
|i20 : degrees B1                            |
|                                            |
|o20 = {{1}, {1}}                            |
|                                            |
|o20 : List                                  |
+--------------------------------------------+
|i21 : truncate(2, B1^1)                     |
|                                            |
|o21 = image | y2 xy x2 |                    |
|                                            |
|                                1           |
|o21 : B1-module, submodule of B1            |
+--------------------------------------------+
|i22 : truncate(2, ideal(a^3*x, b*y^2))      |
|                                            |
|                2   3      3 2              |
|o22 = ideal (b*y , a x*y, a x )             |
|                                            |
|o22 : Ideal of B1                           |
+--------------------------------------------+

Caveat
======

The behavior of this function has changed as of Macaulay2 version 1.13. This is
a (potentially) breaking change. Before, it used a less useful notion of
truncation, involving the heft vector, and was often not what one wanted in the
multi-graded case. Additionally, in the tower ring case, when the coefficient
ring had variables of nonzero degree, sometimes incorrect answers resulted.

Also, the function expects a graded module, ring, or ideal, but this is not
checked, and some answer is returned.

See also
========

  * basis (Macaulay2Doc) -- basis or generating set of all or part
    of a ring, ideal or module
  * module (Macaulay2Doc) -- make or get a module
  * comodule (Macaulay2Doc) -- submodule to quotient module

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

  * "truncate(List,Ideal)"
  * truncate(List,Module) -- truncation of
    the graded ring, ideal or module at a specified degree or set of degrees
  * "truncate(List,Ring)"
  * "truncate(ZZ,Ideal)"
  * "truncate(ZZ,Module)"
  * "truncate(ZZ,Ring)"

truncate(List,Matrix) -- truncation of a map of free modules
************************************************************

Synopsis
========

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate(degs, f)
  * Inputs:
      * degs, a list (Macaulay2Doc), an integer (Macaulay2Doc),
        or a list (Macaulay2Doc), a single
        degree, a multidegree, or a list of degrees or multidegrees
      * f, a matrix (Macaulay2Doc), a graded map between graded
        modules (not necessarily free modules)
  * Optional inputs (Macaulay2Doc),:
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, indicates whether the source and target of the
        result should be trimmed (Macaulay2Doc),
  * Outputs:
      * a matrix (Macaulay2Doc), a graded map between the
        truncations of the source and target of $f$

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

This function truncates the source and target of a module map, and returns the
induced map between them.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d, Degrees => {{1,3},{1,0},{1,3},{1,2}}];                 |
+-----------------------------------------------------------------------------+
|i2 : I = ideal "a,b2,c3,d4"                                                  |
|                                                                             |
|                2   3   4                                                    |
|o2 = ideal (a, b , c , d )                                                   |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : C = res I                                                               |
|                                                                             |
|      1      4      6      4      1                                          |
|o3 = R  <-- R  <-- R  <-- R  <-- R  <-- 0                                    |
|                                                                             |
|     0      1      2      3      4      5                                    |
|                                                                             |
|o3 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i4 : g1 = truncate({1,1}, C.dd_1)                                            |
|                                                                             |
|o4 = {1, 2} | 0 b2 0  0  0  d3 |                                             |
|     {1, 3} | 0 0  b2 0  c2 0  |                                             |
|     {1, 3} | 1 0  0  b2 0  0  |                                             |
|                                                                             |
|o4 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i5 : g2 = truncate({1,1}, C.dd_2)                                            |
|                                                                             |
|o5 = {1, 3} | -b2 -c3 0   -d4 0   0   |                                      |
|     {3, 2} | 0   0   0   0   -d3 0   |                                      |
|     {3, 3} | 0   0   -c2 0   0   0   |                                      |
|     {3, 3} | 1   0   0   0   0   0   |                                      |
|     {3, 9} | 0   a   b2  0   0   -d4 |                                      |
|     {4, 8} | 0   0   0   a   b2  c3  |                                      |
|                                                                             |
|o5 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i6 : g3 = truncate({1,1}, C.dd_3)                                            |
|                                                                             |
|o6 = {3, 3}  | c3  d4  0   0   |                                             |
|     {4, 12} | -b2 0   d4  0   |                                             |
|     {5, 9}  | a   0   0   d4  |                                             |
|     {5, 11} | 0   -b2 -c3 0   |                                             |
|     {6, 8}  | 0   a   0   -c3 |                                             |
|     {7, 17} | 0   0   a   b2  |                                             |
|                                                                             |
|o6 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i7 : g4 = truncate({1,1}, C.dd_4)                                            |
|                                                                             |
|o7 = {6, 12} | -d4 |                                                         |
|     {7, 11} | c3  |                                                         |
|     {8, 20} | -b2 |                                                         |
|     {9, 17} | a   |                                                         |
|                                                                             |
|o7 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i8 : D = chainComplex {g1, g2, g3, g4}                                       |
|                                                                             |
|o8 = image | d c a | <-- image {1, 3} | 1 0 0 0 0 0 | <-- image {3, 3}  | 1 0|
|                               {2, 0} | 0 d c a 0 0 |           {4, 12} | 0 1|
|     0                         {3, 9} | 0 0 0 0 1 0 |           {5, 9}  | 0 0|
|                               {4, 8} | 0 0 0 0 0 1 |           {5, 11} | 0 0|
|                                                                {6, 8}  | 0 0|
|                         1                                      {7, 17} | 0 0|
|                                                                             |
|                                                          2                  |
|                                                                             |
|o8 : ChainComplex                                                            |
|-----------------------------------------------------------------------------|
|0 0 0 0 | <-- image {6, 12} | 1 0 0 0 | <-- image {10, 20} | 1 |             |
|0 0 0 0 |           {7, 11} | 0 1 0 0 |                                      |
|1 0 0 0 |           {8, 20} | 0 0 1 0 |     4                                |
|0 1 0 0 |           {9, 17} | 0 0 0 1 |                                      |
|0 0 1 0 |                                                                    |
|0 0 0 1 |     3                                                              |
+-----------------------------------------------------------------------------+

This functor is exact.

+-----------------------------------------------------------+
|i9 : prune HH D                                            |
|                                                           |
|o9 = 0 : cokernel {1, 2} | a c  0 b2 0  0  d3 |            |
|                  {1, 3} | 0 -d a 0  c2 b2 0  |            |
|                                                           |
|     1 : 0                                                 |
|                                                           |
|     2 : 0                                                 |
|                                                           |
|     3 : 0                                                 |
|                                                           |
|     4 : 0                                                 |
|                                                           |
|o9 : GradedModule                                          |
+-----------------------------------------------------------+
|i10 : HH_0 D == truncate({1,1}, comodule ideal"a,b2,c3,d4")|
|                                                           |
|o10 = true                                                 |
+-----------------------------------------------------------+

See also
========

  * truncate(List,Module) (missing documentation)

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

  * truncate(List,Matrix) -- truncation of
    a map of free modules
  * "truncate(ZZ,Matrix)"