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

MultigradedImplicitization -- Package for levaraging multigradings to solve implicitization problems
****************************************************************************************************

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

The MultigradedImplicitization package provides methods for computing the
maximal $\mathbb{Z}^k$ grading in which the kernel of a polynomial map $F$ is
homogeneous and exploiting it to find generators of $\ker(F)$. This package is
particularly useful for problems from algebraic statistics which often involve
highly structured maps $F$ which are often naturally homogeneous in a larger
multigrading than the standard $\mathbb{Z}$-multigrading given by total degree.
For more information on this approach see the following:

References:

[1] Cummings, J., & Hollering , B. (2023). Computing Implicitizations of
Multi-Graded Polynomial Maps. arXiv preprint arXiv:2311.07678.

[2] Cummings, J., & Hauenstein, J. (2023). Multi-graded Macaulay Dual Spaces.
arXiv preprint arXiv:2310.11587.

[3] Cummings, J., Hollering, B., & Manon, C. (2024). Invariants for level-1
phylogenetic networks under the cavendar-farris-neyman model. Advances in
Applied Mathematics, 153, 102633.

Authors
=======

  * Joseph Cummings (see https://sites.google.com/view/josephcummingsuky/home )
    <josephcummings03@gmail.com>
  * Benjamin Hollering (see https://sites.google.com/view/benhollering )
    <benhollering@gmail.com>
  * Mahrud Sayrafi (see https://math.umn.edu/~mahrud ) <mahrud@umn.edu>

Version
=======

This documentation describes version 1.1 of MultigradedImplicitization,
released May 15, 2025.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{MultigradedImplicitizationSource,                                      |
|  title = {{MultigradedImplicitization: solving implicitization problems usin|
|  author = {Joseph Cummings and Benjamin Hollering and Mahrud Sayrafi},      |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|-----------------------------------------------------------------------------|
|g multigradings. Version~1.1}},                                              |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * componentsOfKernel -- Finds all minimal
        generators up to a given total degree in the kernel of a ring map
      * computeComponent -- Finds all minimal
        generators of a given multidegree in the kernel of a ring map
      * interpolateComponent -- Finds all minimal
        generators of a given multidegree in the kernel of a ring map by
        sampling points in the corresponding variety and then interpolating.
      * maxGrading -- computes the maximal $\mathbb{Z}^k$
        grading such that $\ker(F)$ is homogeneous
      * trimBasisInDegree -- Finds a basis for the
        homogeneous component of a graded ring but removes basis elements which
        correspond to previously computed generators.
  * Methods
      * "componentsOfKernel(Number,RingMap)" -- see componentsOfKernel,
        -- Finds all minimal generators up to a given total
        degree in the kernel of a ring map
      * "computeComponent(List,Ring,RingMap)" -- see computeComponent,
        -- Finds all minimal generators of a given
        multidegree in the kernel of a ring map
      * "computeComponent(List,Ring,RingMap,HashTable)" -- see
        computeComponent, -- Finds all minimal generators of
        a given multidegree in the kernel of a ring map
      * "computeComponent(List,Ring,RingMap,Matrix)" -- see
        computeComponent, -- Finds all minimal generators of
        a given multidegree in the kernel of a ring map
      * "interpolateComponent(List,Matrix)" -- see interpolateComponent,
        -- Finds all minimal generators of a given
        multidegree in the kernel of a ring map by sampling points in the
        corresponding variety and then interpolating.
      * "interpolateComponent(List,Ring,List,HashTable)" -- see
        interpolateComponent, -- Finds all minimal
        generators of a given multidegree in the kernel of a ring map by
        sampling points in the corresponding variety and then interpolating.
      * "interpolateComponent(List,Ring,RingMap)" -- see
        interpolateComponent, -- Finds all minimal
        generators of a given multidegree in the kernel of a ring map by
        sampling points in the corresponding variety and then interpolating.
      * "maxGrading(RingMap)" -- see maxGrading, -- computes
        the maximal $\mathbb{Z}^k$ grading such that $\ker(F)$ is homogeneous
      * "trimBasisInDegree(List,Ring,HashTable)" -- see
        trimBasisInDegree, -- Finds a basis for the
        homogeneous component of a graded ring but removes basis elements which
        correspond to previously computed generators.
      * "trimBasisInDegree(List,Ring,List,HashTable)" -- see
        trimBasisInDegree, -- Finds a basis for the
        homogeneous component of a graded ring but removes basis elements which
        correspond to previously computed generators.
  * Symbols
      * Grading -- a matrix which gives a homogeneous
        multigrading on a polynomial map
      * PreviousGens -- a list previously computed
        generators of the kernel of a map
      * ReturnTargetGrading -- return the grading
        on the target ring of a polynomial map which induces a grading on the
        kernel
      * UseInterpolation -- use interpolation to find
        polynomials in the kernel of a map
      * UseMatroid -- use the algebraic matroid of a
        polynomial map represented by the jacobian to skip computation of
        irrelevant components of the kernel

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

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

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

The source of this document is in MultigradedImplicitization.m2:471:0.

CoefficientRing -- ground field over which to sample points from during interpolation
*************************************************************************************

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

This option can be used to specify the ground field over which to sample points
from the image of a polynomial map. The default value is ZZ/32003.

Functions with optional argument named CoefficientRing:
=======================================================

  * "componentsOfKernel(...,CoefficientRing=>...)"
  * flattenRing(...,CoefficientRing=>...) (Macaulay2Doc),
    --
    specify the coefficient ring of the flattened ring
  * "generators(...,CoefficientRing=>...)" -- see generators(Ring) (Macaulay2Doc),
    -- the list of generators of a ring
  * "Grassmannian(...,CoefficientRing=>...)" -- see Grassmannian (Macaulay2Doc),
    -- compute the ideal of the Grassmannian of
    linear subspaces of a vector space
  * random(...,CoefficientRing=>...) (missing documentation)
  * "Schubert(...,CoefficientRing=>...)" -- see Schubert (Macaulay2Doc),
    -- compute the Plücker ideal of a Schubert variety

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

The object CoefficientRing (Macaulay2Doc), is a
symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:842:0.

componentsOfKernel -- Finds all minimal generators up to a given total degree in the kernel of a ring map
*********************************************************************************************************

  * Usage:
        componentsOfKernel(d, F)
  * Inputs:
      * d, a list (Macaulay2Doc), the total degree at which to stop
        computing generators
      * F, a ring map (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Grading, => a matrix (Macaulay2Doc),
        default value null, a matrix whose columns give a homogeneous
        multigrading on $\ker(F)$
      * UseMatroid, => a Boolean value (Macaulay2Doc),
        default value true, use the jacobian of $F$ to
        detect if a homogeneous component may contain polynomials in the
        kernel.
      * UseInterpolation, => a Boolean value (Macaulay2Doc),
        default value false, use interpolation instead
        of symbolically computing polynomials in each homogeneous component.
      * CoefficientRing, => a ring (Macaulay2Doc),
        default value ZZ/32003, the ground field which is
        used to sample points from $V(\ker(F))$
      * Verbose,
        => a Boolean value (Macaulay2Doc), default value true,
        display detailed output
  * Outputs:
      * a mutable hash table (Macaulay2Doc), A mutable
        hashtable whose keys correspond to all homogeneous components of
        $\ker(F)$ and values correspond to generators in $\ker(F)$ with those
        components

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

Computes all minimal generators of $\ker(F)$ which are of total degree at most
d.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1,1,1,0,0,0}, {0,0,0,1,1,1}, {1,0,0,1,0,0}, {0,1,0,0,1,0}, |
|                                                                             |
|o1 = | 1 1 1 0 0 0 |                                                         |
|     | 0 0 0 1 1 1 |                                                         |
|     | 1 0 0 1 0 0 |                                                         |
|     | 0 1 0 0 1 0 |                                                         |
|     | 0 0 1 0 0 1 |                                                         |
|                                                                             |
|              5       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|{0,0,1,0,0,1}}                                                               |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x_(1,1)..x_(2,3)];                                               |
+-----------------------------------------------------------------------------+
|i3 : S = QQ[t_1..t_2, s_1..s_3];                                             |
+-----------------------------------------------------------------------------+
|i4 : F = map(S, R, {t_1*s_1, t_1*s_2, t_1*s_3, t_2*s_1, t_2*s_2, t_2*s_3})   |
|                                                                             |
|o4 = map (S, R, {t s , t s , t s , t s , t s , t s })                        |
|                  1 1   1 2   1 3   2 1   2 2   2 3                          |
|                                                                             |
|o4 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : peek componentsOfKernel(2, F)                                           |
|warning: computation begun over finite field. resulting polynomials may not  |
|computing total degree: 1                                                    |
|number of monomials = 6                                                      |
|number of distinct multidegrees = 6                                          |
| -- .00216718s elapsed                                                       |
|computing total degree: 2                                                    |
|number of monomials = 21                                                     |
|number of distinct multidegrees = 18                                         |
| -- .00896174s elapsed                                                       |
|                                                                             |
|o5 = MutableHashTable{{0, 1, 0, 0, 1} => {}                   }              |
|                      {0, 1, 0, 1, 0} => {}                                  |
|                      {0, 1, 1, 0, 0} => {}                                  |
|                      {0, 2, 0, 0, 2} => {}                                  |
|                      {0, 2, 0, 1, 1} => {}                                  |
|                      {0, 2, 0, 2, 0} => {}                                  |
|                      {0, 2, 1, 0, 1} => {}                                  |
|                      {0, 2, 1, 1, 0} => {}                                  |
|                      {0, 2, 2, 0, 0} => {}                                  |
|                      {1, 0, 0, 0, 1} => {}                                  |
|                      {1, 0, 0, 1, 0} => {}                                  |
|                      {1, 0, 1, 0, 0} => {}                                  |
|                      {1, 1, 0, 0, 2} => {}                                  |
|                      {1, 1, 0, 1, 1} => {x   x    - x   x   }               |
|                                           1,3 2,2    1,2 2,3                |
|                      {1, 1, 0, 2, 0} => {}                                  |
|                      {1, 1, 1, 0, 1} => {x   x    - x   x   }               |
|                                           1,3 2,1    1,1 2,3                |
|                      {1, 1, 1, 1, 0} => {x   x    - x   x   }               |
|                                           1,2 2,1    1,1 2,2                |
|                      {1, 1, 2, 0, 0} => {}                                  |
|                      {2, 0, 0, 0, 2} => {}                                  |
|                      {2, 0, 0, 1, 1} => {}                                  |
|                      {2, 0, 0, 2, 0} => {}                                  |
|                      {2, 0, 1, 0, 1} => {}                                  |
|                      {2, 0, 1, 1, 0} => {}                                  |
|                      {2, 0, 2, 0, 0} => {}                                  |
|-----------------------------------------------------------------------------|
|lie in the ideal                                                             |
+-----------------------------------------------------------------------------+

If a grading in which $\ker(F)$ is homogeneous is already known or a specific
grading is desired then the option Grading can be used to specify this. In this
case the columns of the matrix Grading are automatically used to grade the
source of $F$.

Caveat
======

If the option UseInterpolation is set to true then interpolateComponent,
is used to compute polynomials in each homogeneous
component instead of computeComponent, which is the
default. In this case, the resulting polynomials are no longer guaranteed to be
in $\ker(F)$ but instead belong to the ideal with high probability. Setting
this option to true will often significantly speed up computation, especially
when computing high degree polynomials in the kernel of dense polynomial maps.

Ways to use componentsOfKernel:
===============================

  * "componentsOfKernel(Number,RingMap)"

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

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

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

The source of this document is in MultigradedImplicitization.m2:604:0.

componentsOfKernel(...,Verbose=>...) -- display detailed output during computation
**********************************************************************************

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

This option is a boolean that determines if detailed output should be displayed
during the kernel computation. This option is true by default.

Functions with optional argument named Verbose:
===============================================

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * componentsOfKernel(...,Verbose=>...)
    -- display detailed
    output during computation
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

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

  * Default value: true (Macaulay2Doc),
  * Function: componentsOfKernel, -- Finds all
    minimal generators up to a given total degree in the kernel of a ring map
  * Option key: Verbose (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in MultigradedImplicitization.m2:863:0.

computeComponent -- Finds all minimal generators of a given multidegree in the kernel of a ring map
***************************************************************************************************

  * Usage:
        computeComponent(deg, dom, F, M)
        computeComponent(deg, dom, F, B)
        computeComponent(deg, dom, F)
  * Inputs:
      * deg, a list (Macaulay2Doc), the degree of the homogeneous
        component to compute
      * dom, a ring (Macaulay2Doc), a graded ring which is the
        source of a homogeneous ring map $F$
      * F, a ring map (Macaulay2Doc), a map whose kernel is
        homogeneous in the grading of dom
      * M, a matrix (Macaulay2Doc), a monomial basis for the
        homogeneous component of deg with degree deg
      * B, a hash table (Macaulay2Doc), a hashtable which
        contains all bases of homogeneous components which correspond to lower
        total degrees than deg
  * Optional inputs (Macaulay2Doc),:
      * PreviousGens, => a list (Macaulay2Doc),
        default value {}, a list of generators of the kernel which have lower
        total degree
  * Outputs:
      * a matrix (Macaulay2Doc), A list of minimal generators for
        $\ker(F)$ which are in the homogeneous component of degree deg

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

Computes all minimal generators of $\ker(F)$ which are in the homogeneous
component of degree deg

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1,1,1,0,0,0}, {0,0,0,1,1,1}, {1,0,0,1,0,0}, {0,1,0,0,1,0}, |
|                                                                             |
|o1 = | 1 1 1 0 0 0 |                                                         |
|     | 0 0 0 1 1 1 |                                                         |
|     | 1 0 0 1 0 0 |                                                         |
|     | 0 1 0 0 1 0 |                                                         |
|     | 0 0 1 0 0 1 |                                                         |
|                                                                             |
|              5       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|{0,0,1,0,0,1}}                                                               |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x_(1,1)..x_(2,3)];                                               |
+-----------------------------------------------------------------------------+
|i3 : S = QQ[t_1..t_2, s_1..s_3];                                             |
+-----------------------------------------------------------------------------+
|i4 : F = map(S, R, {t_1*s_1, t_1*s_2, t_1*s_3, t_2*s_1, t_2*s_2, t_2*s_3})   |
|                                                                             |
|o4 = map (S, R, {t s , t s , t s , t s , t s , t s })                        |
|                  1 1   1 2   1 3   2 1   2 2   2 3                          |
|                                                                             |
|o4 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : dom = newRing(R, Degrees => A);                                         |
+-----------------------------------------------------------------------------+
|i6 : computeComponent({1,1,0,1,1}, dom, F)                                   |
|                                                                             |
|o6 = {x   x    - x   x   }                                                   |
|       1,3 2,2    1,2 2,3                                                    |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

The option PreviousGens can be used to specify a set of previously computed
generators. In the case that a monomial basis or hash table of monomial bases
is not given then trimBasisInDegree, will be used to
compute a monomial basis and PreviousGens will be used to trim this basis.

Ways to use computeComponent:
=============================

  * "computeComponent(List,Ring,RingMap)"
  * "computeComponent(List,Ring,RingMap,HashTable)"
  * "computeComponent(List,Ring,RingMap,Matrix)"

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

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

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

The source of this document is in MultigradedImplicitization.m2:651:0.

Grading -- a matrix which gives a homogeneous multigrading on a polynomial map
******************************************************************************

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

The option Grading is a matrix (Macaulay2Doc), that allows one to
specify a specific multigrading in which a polynomial map is homogeneous in.

Functions with optional argument named Grading:
===============================================

  * "componentsOfKernel(...,Grading=>...)"

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

The object Grading, is a symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:723:0.

interpolateComponent -- Finds all minimal generators of a given multidegree in the kernel of a ring map by sampling points in the corresponding variety and then interpolating.
*******************************************************************************************************************************************************************************

  * Usage:
        interpolateComponent(P, M)
        interpolateComponent(deg, dom, F, B)
        interpolateComponent(deg, dom, F)
  * Inputs:
      * deg, a list (Macaulay2Doc), the degree of the homogeneous
        component to compute
      * dom, a ring (Macaulay2Doc), a graded ring which is the
        source of a homogeneous ring map $F$
      * F, a ring map (Macaulay2Doc), a map whose kernel is
        homogeneous in the grading of dom
      * M, a matrix (Macaulay2Doc), a monomial basis for the
        homogeneous component of deg with degree deg
      * P, a list (Macaulay2Doc), a list of options which
        correspond to points from $V(\ker(F))$ which are used to interpolate
        the monomials in M
      * B, a hash table (Macaulay2Doc), a hashtable which
        contains all bases of homogeneous components which correspond to lower
        total degrees than deg
  * Optional inputs (Macaulay2Doc),:
      * PreviousGens, => a list (Macaulay2Doc),
        default value {}, a list of generators of the kernel which have lower
        total degree
  * Outputs:
      * a matrix (Macaulay2Doc), A list of minimal generators for
        $\ker(F)$ which are in the homogeneous component of degree deg

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

Computes all minimal generators of $\ker(F)$ which are in the homogeneous
component of degree deg

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1,1,1,0,0,0}, {0,0,0,1,1,1}, {1,0,0,1,0,0}, {0,1,0,0,1,0}, |
|                                                                             |
|o1 = | 1 1 1 0 0 0 |                                                         |
|     | 0 0 0 1 1 1 |                                                         |
|     | 1 0 0 1 0 0 |                                                         |
|     | 0 1 0 0 1 0 |                                                         |
|     | 0 0 1 0 0 1 |                                                         |
|                                                                             |
|              5       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|{0,0,1,0,0,1}}                                                               |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x_(1,1)..x_(2,3)];                                               |
+-----------------------------------------------------------------------------+
|i3 : S = QQ[t_1..t_2, s_1..s_3];                                             |
+-----------------------------------------------------------------------------+
|i4 : F = map(S, R, {t_1*s_1, t_1*s_2, t_1*s_3, t_2*s_1, t_2*s_2, t_2*s_3})   |
|                                                                             |
|o4 = map (S, R, {t s , t s , t s , t s , t s , t s })                        |
|                  1 1   1 2   1 3   2 1   2 2   2 3                          |
|                                                                             |
|o4 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : dom = newRing(R, Degrees => A);                                         |
+-----------------------------------------------------------------------------+
|i6 : interpolateComponent({1,1,0,1,1}, dom, F)                               |
|                                                                             |
|o6 = {x   x    - x   x   }                                                   |
|       1,3 2,2    1,2 2,3                                                    |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

The option PreviousGens can be used to specify a set of previously computed
generators. In the case that a monomial basis or hash table of monomial bases
is not given then trimBasisInDegree, will be used to
compute a monomial basis and PreviousGens will be used to trim this basis.

Caveat
======

The polynomials returned by this method belong to $\ker(F)$ with high
probability but may not actually belong to the kernel. Further verification is
recommended to ensure that the resulting polynomials actually belong to
$\ker(F)$.

Ways to use interpolateComponent:
=================================

  * "interpolateComponent(List,Matrix)"
  * "interpolateComponent(List,Ring,List,HashTable)"
  * "interpolateComponent(List,Ring,RingMap)"

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

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

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

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

maxGrading -- computes the maximal $\mathbb{Z}^k$ grading such that $\ker(F)$ is homogeneous
********************************************************************************************

  * Usage:
        maxGrading(F)
  * Inputs:
      * F, a ring map (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ReturnTargetGrading, => a Boolean value (Macaulay2Doc),
        default value false, a boolean which
        encodes whether or not to also return the grading on target(F) which
        induces the grading on $\ker(F)$
  * Outputs:
      * a matrix (Macaulay2Doc), the maximal $\mathbb{Z}^k$
        grading in which $\ker(F)$ is homogeneous

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

Computes the maximal $\mathbb{Z}^k$ grading such that the $\ker(F)$ is
homogeneous. The columns of the output matrix are the degrees of the
corresponding variables in source(F). For example, the snippet below shows that
the maximal grading of a toric ideal is exactly the integer matrix which
encodes the monomial map parameterizing the ideal.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1,1,1,0,0,0}, {0,0,0,1,1,1}, {1,0,0,1,0,0}, {0,1,0,0,1,0}, |
|                                                                             |
|o1 = | 1 1 1 0 0 0 |                                                         |
|     | 0 0 0 1 1 1 |                                                         |
|     | 1 0 0 1 0 0 |                                                         |
|     | 0 1 0 0 1 0 |                                                         |
|     | 0 0 1 0 0 1 |                                                         |
|                                                                             |
|              5       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|{0,0,1,0,0,1}}                                                               |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x_(1,1)..x_(2,3)];                                               |
+-----------------------------------------------------------------------------+
|i3 : S = QQ[t_1..t_2, s_1..s_3];                                             |
+-----------------------------------------------------------------------------+
|i4 : F = map(S, R, {t_1*s_1, t_1*s_2, t_1*s_3, t_2*s_1, t_2*s_2, t_2*s_3})   |
|                                                                             |
|o4 = map (S, R, {t s , t s , t s , t s , t s , t s })                        |
|                  1 1   1 2   1 3   2 1   2 2   2 3                          |
|                                                                             |
|o4 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : maxGrading(F)                                                           |
|                                                                             |
|o5 = | 1 1 1 0 0 0 |                                                         |
|     | 0 0 0 1 1 1 |                                                         |
|     | 1 0 0 1 0 0 |                                                         |
|     | 0 1 0 0 1 0 |                                                         |
|     | 0 0 1 0 0 1 |                                                         |
|                                                                             |
|              5       6                                                      |
|o5 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+

The option ReturnTargetGrading returns a matrix which also gives the
corresponding grading on the target ring of $F$ which induces the grading on
$\ker(F)$. This option is false by default.

+-----------------------------------------------+
|i6 : maxGrading(F, ReturnTargetGrading => true)|
|                                               |
|o6 = | 1 1 1 0 0 0 1 0 0 0 0 |                 |
|     | 0 0 0 1 1 1 0 1 0 0 0 |                 |
|     | 1 0 0 1 0 0 0 0 1 0 0 |                 |
|     | 0 1 0 0 1 0 0 0 0 1 0 |                 |
|     | 0 0 1 0 0 1 0 0 0 0 1 |                 |
|                                               |
|              5       11                       |
|o6 : Matrix ZZ  <-- ZZ                         |
+-----------------------------------------------+

Ways to use maxGrading:
=======================

  * "maxGrading(RingMap)"

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

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

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

The source of this document is in MultigradedImplicitization.m2:509:0.

PreviousGens -- a list previously computed generators of the kernel of a map
****************************************************************************

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

The option PreviousGens is a list (Macaulay2Doc), of polynomials of
total degree at most $d-1$ which can be used with computeComponent,
to trim the monomial basis for that multidegree.

Functions with optional argument named PreviousGens:
====================================================

  * "computeComponent(...,PreviousGens=>...)"
  * "interpolateComponent(...,PreviousGens=>...)"

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

The object PreviousGens, is a symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:794:0.

ReturnTargetGrading -- return the grading on the target ring of a polynomial map which induces a grading on the kernel
**********************************************************************************************************************

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

The option ReturnTargetGrading is a boolean (Macaulay2Doc), which
can be used with maxGrading. This option is false by
default. If it is set to true then the full grading on the elimination ideal of
a polynomial map $F$ will be returned instead of only returning the part of the
grading which corresponds to the source of $F$.

Functions with optional argument named ReturnTargetGrading:
===========================================================

  * "maxGrading(...,ReturnTargetGrading=>...)"

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

The object ReturnTargetGrading, is a symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:770:0.

trimBasisInDegree -- Finds a basis for the homogeneous component of a graded ring but removes basis elements which correspond to previously computed generators.
****************************************************************************************************************************************************************

  * Usage:
        trimBasisInDegree(deg, dom, G, B)
        trimBasisInDegree(deg, dom, B)
  * Inputs:
      * deg, a list (Macaulay2Doc), the degree of the homogeneous
        component to compute
      * dom, a ring (Macaulay2Doc), a graded ring which is the
        source of a homogeneous ring map $F$
      * G, a list (Macaulay2Doc), a list of previously computed
        generators of $\ker(F)$
      * B, a hash table (Macaulay2Doc), a hashtable which
        contains all bases of homogeneous components which correspond to lower
        total degrees than deg
  * Outputs:
      * a matrix (Macaulay2Doc), A monomial basis for the
        homogeneous component of degree deg of dom with any monomials which
        cannot be involved in new generators of $\ker(F)$ removed.

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

Computes a monomial basis for the homogeneous component of degree deg of the
graded ring dom which is the source of a ring map $F$. Monomials which
correspond to previously computed relations which are in G are automatically
removed since they will not yield new generators in $\ker(F)$ when applying
computeComponent, to this basis.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1,1,1,0,0,0,0,0,0}, {0,0,0,1,1,1,0,0,0},                   |
|                                                                             |
|              5       9                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|{0,0,0,0,0,0,1,1,1}, {1,0,0,1,0,0,1,0,0}, {0,1,0,0,1,0,0,1,0}};              |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x_1..x_(numcols A)];                                             |
+-----------------------------------------------------------------------------+
|i3 : dom = newRing(R, Degrees => A);                                         |
+-----------------------------------------------------------------------------+
|i4 : use R;                                                                  |
+-----------------------------------------------------------------------------+
|i5 : S = QQ[t_1..t_(numrows A)];                                             |
+-----------------------------------------------------------------------------+
|i6 : F = map(S, R, apply(numcols(A), i -> S_(flatten entries A_i)));         |
|                                                                             |
|o6 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : B = basis(1, source F) | basis(2, source F) | basis(3, source F);       |
|                                                                             |
|             1      219                                                      |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i8 : lats = unique apply(flatten entries B, i -> degree(sub(i, dom)));       |
+-----------------------------------------------------------------------------+
|i9 : basisHash = hashTable apply(lats, deg -> {deg, sub(basis(deg, dom),     |
|-----------------------------------------------------------------------------|
|R)});                                                                        |
+-----------------------------------------------------------------------------+
|i10 : trimBasisInDegree({2,1,0,1,1},  dom, {x_2*x_4-x_1*x_5, x_3*x_4-x_1*x_6,|
|                                                                             |
|o10 = | x_2x_3x_4 |                                                          |
|                                                                             |
|              1      1                                                       |
|o10 : Matrix R  <-- R                                                        |
|-----------------------------------------------------------------------------|
|x_3*x_5-x_2*x_6}, basisHash)                                                 |
+-----------------------------------------------------------------------------+

Observe that after trimming we get a smaller monomial basis for this
homogeneous component. The full monomial basis is

+---------------------------------------+
|i11 : basis({2,1,0,1,1}, dom)          |
|                                       |
|o11 = | x_1x_2x_6 x_1x_3x_5 x_2x_3x_4 ||
|                                       |
|                1        3             |
|o11 : Matrix dom  <-- dom              |
+---------------------------------------+

Ways to use trimBasisInDegree:
==============================

  * "trimBasisInDegree(List,Ring,HashTable)"
  * "trimBasisInDegree(List,Ring,List,HashTable)"

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

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

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

The source of this document is in MultigradedImplicitization.m2:556:0.

UseInterpolation -- use interpolation to find polynomials in the kernel of a map
********************************************************************************

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

This option is a boolean that allows one to specify if interpolation should be
used to find polynomials in each homogeneous component of $\ker(F)$. This
option is false by default. If it is set to false then computeComponent,
will be used to find polynomials in each homogeneous
component which is purely symbolic. If it is set to true then
interpolateComponent, will be used to to find polynomials
in each homogeneous component which are in the kernel with high probability.
Setting this option to true will often significantly speed up the computation
for large polynomial maps, especially in higher degree components.

Functions with optional argument named UseInterpolation:
========================================================

  * "componentsOfKernel(...,UseInterpolation=>...)"

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

The object UseInterpolation, is a symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:819:0.

UseMatroid -- use the algebraic matroid of a polynomial map represented by the jacobian to skip computation of irrelevant components of the kernel
**************************************************************************************************************************************************

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

The option UseMatroid is a boolean that allows one to specify if the matroid
given by the jacobian should be used to automatically skip components. This
option is true by default. If it is set to false, then every homogeneous
component will be checked, even if it is impossible for a polynomial with the
necessary support to belong to the kernel. For very small examples, it may be
slightly faster to set this to false.

Functions with optional argument named UseMatroid:
==================================================

  * "componentsOfKernel(...,UseMatroid=>...)"

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

The object UseMatroid, is a symbol (Macaulay2Doc).

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

The source of this document is in MultigradedImplicitization.m2:747:0.