This is MatchingFields.info, produced by Macaulay2, version 1.24.11

MatchingFields -- A package for working with matching fields for Grassmannians and partial flag varieties
*********************************************************************************************************

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

A matching field $\Lambda$ for the Grassmannian Gr($k$, $n$), is a simple
combinatorial object. It may be thought of as a choice of initial term for each
maximal minor of a generic $k \times n$ matrix of variables. For example, take
$k = 2$ and $n = 4$. Let $X = (x_{i,j})$ be a generic $2 \times 4$ matrix of
variables. Suppose that a matching field $\Lambda$ has tuples $\{12, 31, 14,
32, 24, 34\}$. This means that $\Lambda$ distinguishes the term $x_{1,1}
x_{2,2}$ from the maximal minors on columns $1$ and $2$ of $X$: $x_{1,1}
x_{2,2} - x_{1,2} x_{2,1}$. Similarly for the terms $x_{1,3} x_{2,1}$, $x_{1,1}
x_{2,4}$, and so on.

If the terms of all maximal minors distinguished by a matching field are their
initial terms with respect to a fixed weight matrix, then we say that the
matching field is coherent. Each such weight matrix induces a weight vector on
the Pluecker coordinates of the Grassmannian. If the initial ideal of the
Pluecker ideal of the Grassmannian with respect to this weight vector is a
toric ideal, i.e. a prime binomial ideal, then we say that the matching field
gives rise to a toric degeneration of the Grassmannian. By a result of
Sturmfels (1996), a matching field gives rise to a toric degeneration if and
only if the maximal minors of $X$ form a subalgebra basis (or SAGBI basis) with
respect to the order induced by the weight matrix.

This concept naturally generalises to partial flag varieties under the Pluecker
embedding.

The MatchingFields package gives basic functions, to construct many of the
well-studied examples of matching fields. Given a matching field $L$, it is
straight forward to check whether $L$ is coherent, what is a weight matrix that
induces it, and whether is gives rise to a toric degeneration. The package also
produces polytopes associated to matching fields and Newton-Okounkov bodies.

+--------------------------------------------------------------------------+
|i1 : L = grMatchingField(2, 4, {{1,2}, {3,1}, {1,4}, {3,2}, {2,4}, {3,4}})|
|                                                                          |
|o1 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o1 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i2 : isCoherent L                                                         |
|                                                                          |
|o2 = true                                                                 |
+--------------------------------------------------------------------------+
|i3 : getWeightMatrix L                                                    |
|                                                                          |
|o3 = | 0 0  0 0  |                                                        |
|     | 0 -1 1 -2 |                                                        |
|                                                                          |
|              2       4                                                   |
|o3 : Matrix ZZ  <-- ZZ                                                    |
+--------------------------------------------------------------------------+
|i4 : isToricDegeneration L                                                |
|                                                                          |
|o4 = true                                                                 |
+--------------------------------------------------------------------------+

Author
======

  * Oliver Clarke (see https://www.oliverclarkemath.com/ )
    <oliver.clarke@ed.ac.uk>

Version
=======

This documentation describes version 1.2 of MatchingFields.

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

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

Exports
=======

  * Types
      * FlMatchingField -- the class of matching fields
        for partial flag varieties
      * GrMatchingField -- the class of Grassmannian
        matching fields
      * TopeField -- A tope field structure on a matching
        field
  * Functions and commands
      * algebraicMatroid -- The algebraic matroid of
        the tropical cone that induces the matroid
      * algebraicMatroidBases -- The bases of the
        algebraic matroid
      * algebraicMatroidCircuits -- The bases
        of the algebraic matroid
      * amalgamation -- The $i$th amalgamation of a tope
        field
      * diagonalMatchingField -- the diagonal
        matching field
      * flMatchingField -- Construct a matching field
        for a partial flag variety
      * getGrMatchingFields -- The Grassmannian
        matching fields of a Flag matching field
      * getTuples -- The tuples of a matching field
      * getWeightMatrix -- weight matrix that induces
        the matching field
      * getWeightPluecker -- weight of the Pluecker
        variables induced by the weight matrix
      * grMatchingField -- Construct a matching field
        for the Grassmannian variety
      * isCoherent -- Is the matching field coherent
      * isLinkage -- Test if a tope field is linkage
      * isToricDegeneration -- Does the matching
        field give rise to a toric degeneration
      * linearSpanTropCone -- linear span of the
        tropical cone associated to the matching field
      * matchingFieldFromPermutation, --
        matching field parametrised by permutations
      * matchingFieldIdeal -- The toric ideal of a
        matching field
      * matchingFieldPolytope -- The polytope of
        a matching field
      * matchingFieldRingMap -- monomial map of
        the matching field
      * matroidSubdivision -- The matroid
        subdivision induced by the Pluecker weight of a coherent matching field
      * NOBody -- Newton-Okounkov body of the matching field
      * plueckerAlgebra -- Pluecker algebra of a
        (partial) flag variety
      * plueckerIdeal -- The Pluecker ideal of a matching
        field
      * plueckerMap -- The ring map of the Pluecker
        embedding
      * topeField -- Constructor of a tope field
      * weightMatrixCone -- The cone of weight
        matrices that induce the matching field
  * Methods
      * "algebraicMatroid(GrMatchingField)" -- see algebraicMatroid,
        -- The algebraic matroid of the tropical cone that
        induces the matroid
      * "algebraicMatroidBases(GrMatchingField)" -- see
        algebraicMatroidBases, -- The bases of the
        algebraic matroid
      * "algebraicMatroidCircuits(GrMatchingField)" -- see
        algebraicMatroidCircuits, -- The bases of the
        algebraic matroid
      * "amalgamation(ZZ,GrMatchingField)" -- see amalgamation,
        -- The $i$th amalgamation of a tope field
      * "amalgamation(ZZ,TopeField)" -- see amalgamation,
        -- The $i$th amalgamation of a tope field
      * "diagonalMatchingField(List,ZZ)" -- see diagonalMatchingField,
        -- the diagonal matching field
      * "diagonalMatchingField(ZZ)" -- see diagonalMatchingField,
        -- the diagonal matching field
      * "diagonalMatchingField(ZZ,ZZ)" -- see diagonalMatchingField,
        -- the diagonal matching field
      * "flMatchingField(List,Matrix)" -- see flMatchingField,
        -- Construct a matching field for a partial flag
        variety
      * "flMatchingField(List,ZZ,List)" -- see flMatchingField,
        -- Construct a matching field for a partial flag
        variety
      * "flMatchingField(Matrix)" -- see flMatchingField,
        -- Construct a matching field for a partial flag
        variety
      * FlMatchingField == FlMatchingField
        -- equality of flag matching fields
      * "getGrMatchingFields(FlMatchingField)" -- see
        getGrMatchingFields, -- The Grassmannian matching
        fields of a Flag matching field
      * "getTuples(FlMatchingField)" -- see getTuples, -- The
        tuples of a matching field
      * "getTuples(GrMatchingField)" -- see getTuples, -- The
        tuples of a matching field
      * getTuples(TopeField) -- tuples of a
        tope field
      * "getWeightMatrix(FlMatchingField)" -- see getWeightMatrix,
        -- weight matrix that induces the matching field
      * "getWeightMatrix(GrMatchingField)" -- see getWeightMatrix,
        -- weight matrix that induces the matching field
      * "getWeightPluecker(FlMatchingField)" -- see getWeightPluecker,
        -- weight of the Pluecker variables induced by the
        weight matrix
      * "getWeightPluecker(GrMatchingField)" -- see getWeightPluecker,
        -- weight of the Pluecker variables induced by the
        weight matrix
      * "grMatchingField(Matrix)" -- see grMatchingField,
        -- Construct a matching field for the Grassmannian
        variety
      * "grMatchingField(ZZ,ZZ,List)" -- see grMatchingField,
        -- Construct a matching field for the Grassmannian
        variety
      * GrMatchingField == GrMatchingField
        -- equality of Grassmannian matching fields
      * "isCoherent(FlMatchingField)" -- see isCoherent, --
        Is the matching field coherent
      * "isCoherent(GrMatchingField)" -- see isCoherent, --
        Is the matching field coherent
      * "isLinkage(GrMatchingField)" -- see isLinkage, -- Test
        if a tope field is linkage
      * "isLinkage(TopeField)" -- see isLinkage, -- Test if a
        tope field is linkage
      * "isToricDegeneration(FlMatchingField)" -- see
        isToricDegeneration, -- Does the matching field
        give rise to a toric degeneration
      * "isToricDegeneration(GrMatchingField)" -- see
        isToricDegeneration, -- Does the matching field
        give rise to a toric degeneration
      * "linearSpanTropCone(GrMatchingField)" -- see linearSpanTropCone,
        -- linear span of the tropical cone associated to
        the matching field
      * "matchingFieldFromPermutation(List,ZZ,List)" -- see
        matchingFieldFromPermutation, -- matching
        field parametrised by permutations
      * "matchingFieldFromPermutation(ZZ,ZZ,List)" -- see
        matchingFieldFromPermutation, -- matching
        field parametrised by permutations
      * "matchingFieldIdeal(FlMatchingField)" -- see matchingFieldIdeal,
        -- The toric ideal of a matching field
      * "matchingFieldIdeal(GrMatchingField)" -- see matchingFieldIdeal,
        -- The toric ideal of a matching field
      * "matchingFieldPolytope(FlMatchingField)" -- see
        matchingFieldPolytope, -- The polytope of a
        matching field
      * "matchingFieldPolytope(GrMatchingField)" -- see
        matchingFieldPolytope, -- The polytope of a
        matching field
      * "matchingFieldRingMap(FlMatchingField)" -- see
        matchingFieldRingMap, -- monomial map of the
        matching field
      * "matchingFieldRingMap(GrMatchingField)" -- see
        matchingFieldRingMap, -- monomial map of the
        matching field
      * "matroidSubdivision(GrMatchingField)" -- see matroidSubdivision,
        -- The matroid subdivision induced by the Pluecker
        weight of a coherent matching field
      * "matroidSubdivision(ZZ,ZZ,List)" -- see matroidSubdivision,
        -- The matroid subdivision induced by the Pluecker
        weight of a coherent matching field
      * "net(FlMatchingField)" -- see net(GrMatchingField),
        -- display a matching field
      * net(GrMatchingField) -- display a
        matching field
      * net(TopeField) -- display a tope field
      * "NOBody(FlMatchingField)" -- see NOBody, --
        Newton-Okounkov body of the matching field
      * "NOBody(GrMatchingField)" -- see NOBody, --
        Newton-Okounkov body of the matching field
      * "plueckerAlgebra(FlMatchingField)" -- see plueckerAlgebra,
        -- Pluecker algebra of a (partial) flag variety
      * "plueckerAlgebra(GrMatchingField)" -- see plueckerAlgebra,
        -- Pluecker algebra of a (partial) flag variety
      * "Grassmannian(GrMatchingField)" -- see plueckerIdeal,
        -- The Pluecker ideal of a matching field
      * "plueckerIdeal(FlMatchingField)" -- see plueckerIdeal,
        -- The Pluecker ideal of a matching field
      * "plueckerIdeal(GrMatchingField)" -- see plueckerIdeal,
        -- The Pluecker ideal of a matching field
      * "plueckerMap(FlMatchingField)" -- see plueckerMap,
        -- The ring map of the Pluecker embedding
      * "plueckerMap(GrMatchingField)" -- see plueckerMap,
        -- The ring map of the Pluecker embedding
      * "topeField(GrMatchingField)" -- see topeField, --
        Constructor of a tope field
      * "topeField(GrMatchingField,List)" -- see topeField, --
        Constructor of a tope field
      * "weightMatrixCone(FlMatchingField)" -- see weightMatrixCone,
        -- The cone of weight matrices that induce the
        matching field
      * "weightMatrixCone(GrMatchingField)" -- see weightMatrixCone,
        -- The cone of weight matrices that induce the
        matching field
  * Symbols
      * ExtraZeroRows -- enlarging a matrix with zero
        rows
      * "VerifyToricDegeneration" -- see linearSpanTropCone,
        -- linear span of the tropical cone associated to
        the matching field
      * RowNum -- the row of the diagonal weight matrix to
        permute
      * ScalingCoefficient -- scale the permuted row
        of the weight matrix
      * "PowerValue" -- see UsePrimePowers, -- use a
        diagonal weight matrix with multiples of certain powers
      * UsePrimePowers -- use a diagonal weight matrix
        with multiples of certain powers

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

The object MatchingFields, is a package (Macaulay2Doc).

Main objects

Constructing matching fields

Basic properties and functions

Rings, ideals and maps

Convex bodies and polyhedra

Dressians and matroids

Topes and tope fields

GrMatchingField -- the class of Grassmannian matching fields
************************************************************

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

Common ways to define Grassmannian matching fields:

  * grMatchingField,-- defined in terms of tuples or a
    weight matrix
  * diagonalMatchingField,-- the diagonal matching
    field
  * matchingFieldFromPermutation,-- family
    of matching fields indexed by permutations

Two Grassmannian matching fields are said to be equal if and only if their
tuples are the same.

Technical details. A Grassmannian matching field is derived from the class
HashTable (Macaulay2Doc). All Grassmannian matching fields
have the following fields:

  * k of type ZZ
  * n of type ZZ
  * tuples of type List, accessible withgetTuples,
  * cache

Everything else, including: weight matrices; polynomial rings, maps and ideals;
polyhedra such as the weight matrix cone and matching field polytope, are all
stored inside the cache. Note that the package does not export the keys, such
as k or n. If you wish to directly address the contents of the GrMatchingField,
then use "debug MatchingFields".

See also
========

  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety

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

  * grMatchingField -- Construct a matching field for
    the Grassmannian variety

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

  * "algebraicMatroid(GrMatchingField)" -- see algebraicMatroid,
    -- The algebraic matroid of the tropical cone that
    induces the matroid
  * "algebraicMatroidBases(GrMatchingField)" -- see
    algebraicMatroidBases, -- The bases of the algebraic
    matroid
  * "algebraicMatroidCircuits(GrMatchingField)" -- see
    algebraicMatroidCircuits, -- The bases of the
    algebraic matroid
  * "amalgamation(ZZ,GrMatchingField)" -- see amalgamation,
    -- The $i$th amalgamation of a tope field
  * "getTuples(GrMatchingField)" -- see getTuples, -- The
    tuples of a matching field
  * "getWeightMatrix(GrMatchingField)" -- see getWeightMatrix,
    -- weight matrix that induces the matching field
  * "getWeightPluecker(GrMatchingField)" -- see getWeightPluecker,
    -- weight of the Pluecker variables induced by the
    weight matrix
  * GrMatchingField == GrMatchingField
    -- equality of Grassmannian matching fields
  * "isCoherent(GrMatchingField)" -- see isCoherent, -- Is
    the matching field coherent
  * "isLinkage(GrMatchingField)" -- see isLinkage, -- Test if
    a tope field is linkage
  * "isToricDegeneration(GrMatchingField)" -- see isToricDegeneration,
    -- Does the matching field give rise to a toric
    degeneration
  * "linearSpanTropCone(GrMatchingField)" -- see linearSpanTropCone,
    -- linear span of the tropical cone associated to the
    matching field
  * "matchingFieldIdeal(GrMatchingField)" -- see matchingFieldIdeal,
    -- The toric ideal of a matching field
  * "matchingFieldPolytope(GrMatchingField)" -- see
    matchingFieldPolytope, -- The polytope of a matching
    field
  * "matchingFieldRingMap(GrMatchingField)" -- see matchingFieldRingMap,
    -- monomial map of the matching field
  * "matroidSubdivision(GrMatchingField)" -- see matroidSubdivision,
    -- The matroid subdivision induced by the Pluecker
    weight of a coherent matching field
  * net(GrMatchingField) -- display a matching
    field
  * "NOBody(GrMatchingField)" -- see NOBody, -- Newton-Okounkov
    body of the matching field
  * "plueckerAlgebra(GrMatchingField)" -- see plueckerAlgebra,
    -- Pluecker algebra of a (partial) flag variety
  * "Grassmannian(GrMatchingField)" -- see plueckerIdeal,
    -- The Pluecker ideal of a matching field
  * "plueckerIdeal(GrMatchingField)" -- see plueckerIdeal,
    -- The Pluecker ideal of a matching field
  * "plueckerMap(GrMatchingField)" -- see plueckerMap, --
    The ring map of the Pluecker embedding
  * "topeField(GrMatchingField)" -- see topeField, --
    Constructor of a tope field
  * "topeField(GrMatchingField,List)" -- see topeField, --
    Constructor of a tope field
  * "weightMatrixCone(GrMatchingField)" -- see weightMatrixCone,
    -- The cone of weight matrices that induce the matching
    field

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

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

FlMatchingField -- the class of matching fields for partial flag varieties
**************************************************************************

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

Common ways to define flag matching fields:

  * flMatchingField,-- defined in terms of tuples or a
    weight matrix
  * diagonalMatchingField,-- the diagonal matching
    field
  * matchingFieldFromPermutation,-- family
    of matching fields indexed by permutations

Technical details. A flag matching field is derived from the class
HashTable (Macaulay2Doc). All flag matching fields have the
following fields:

  * kList of type ZZ
  * n of type ZZ
  * grMatchingFieldList of type List, the list of Grassmannian matching fields
    contained within, accessible with the functiongetGrMatchingFields,
  * cache

Everything else, including: weight matrices; polynomial rings, maps and ideals;
polyhedra such as the weight matrix cone and matching field polytope, are all
stored inside the cache. Note that the package does not export the keys, such
as kList or n. If you wish to directly address the contents of the
FlMatchingField, then use "debug MatchingFields".

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * flMatchingField -- Construct a matching field for a
    partial flag variety

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

  * flMatchingField -- Construct a matching field for a
    partial flag variety

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

  * FlMatchingField == FlMatchingField
    -- equality of flag matching fields
  * "getGrMatchingFields(FlMatchingField)" -- see getGrMatchingFields,
    -- The Grassmannian matching fields of a Flag matching
    field
  * "getTuples(FlMatchingField)" -- see getTuples, -- The
    tuples of a matching field
  * "getWeightMatrix(FlMatchingField)" -- see getWeightMatrix,
    -- weight matrix that induces the matching field
  * "getWeightPluecker(FlMatchingField)" -- see getWeightPluecker,
    -- weight of the Pluecker variables induced by the
    weight matrix
  * "isCoherent(FlMatchingField)" -- see isCoherent, -- Is
    the matching field coherent
  * "isToricDegeneration(FlMatchingField)" -- see isToricDegeneration,
    -- Does the matching field give rise to a toric
    degeneration
  * "matchingFieldIdeal(FlMatchingField)" -- see matchingFieldIdeal,
    -- The toric ideal of a matching field
  * "matchingFieldPolytope(FlMatchingField)" -- see
    matchingFieldPolytope, -- The polytope of a matching
    field
  * "matchingFieldRingMap(FlMatchingField)" -- see matchingFieldRingMap,
    -- monomial map of the matching field
  * "net(FlMatchingField)" -- see net(GrMatchingField),
    -- display a matching field
  * "NOBody(FlMatchingField)" -- see NOBody, -- Newton-Okounkov
    body of the matching field
  * "plueckerAlgebra(FlMatchingField)" -- see plueckerAlgebra,
    -- Pluecker algebra of a (partial) flag variety
  * "plueckerIdeal(FlMatchingField)" -- see plueckerIdeal,
    -- The Pluecker ideal of a matching field
  * "plueckerMap(FlMatchingField)" -- see plueckerMap, --
    The ring map of the Pluecker embedding
  * "weightMatrixCone(FlMatchingField)" -- see weightMatrixCone,
    -- The cone of weight matrices that induce the matching
    field

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

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

grMatchingField -- Construct a matching field for the Grassmannian variety
**************************************************************************

Synopsis
========

  * Usage:
        L = grMatchingField(weightMatrix)
        L = grMatchingField(k, n, tuples)
  * Inputs:
      * k, an integer (Macaulay2Doc), positive integer; the size of
        the tuples of the matching field
      * n, an integer (Macaulay2Doc), positive integer; the tuples
        have entries in 1 .. n
      * weightMatrix, a matrix (Macaulay2Doc), induces the
        matching field
  * Outputs:
      * L, an instance of the type GrMatchingField,

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

This function is the basic constructor for Grassmannian matching fields. The
function outputs an instance of type GrMatchingField,
which represents the matching field and stores all data related and computed
about it.

There are two basic ways to define a Grassmannian matching field. The first way
is to supply a weight matrix that induces the matching field. This produces a
coherent matching field and is well-defined if the matrix is generic.

+-----------------------------------------------------------------------------+
|i1 : M = matrix {{0,0,0,0,0,0}, {1,6,2,5,3,4}, {60,50,10,20,40,30}}          |
|                                                                             |
|o1 = | 0  0  0  0  0  0  |                                                   |
|     | 1  6  2  5  3  4  |                                                   |
|     | 60 50 10 20 40 30 |                                                   |
|                                                                             |
|              3       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : L1 = grMatchingField M                                                  |
|                                                                             |
|o2 = Grassmannian Matching Field for Gr(3, 6)                                |
|                                                                             |
|o2 : GrMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i3 : getTuples L1                                                            |
|                                                                             |
|o3 = {{2, 1, 3}, {2, 1, 4}, {4, 1, 3}, {2, 4, 3}, {2, 1, 5}, {5, 1, 3}, {2,  |
|     ------------------------------------------------------------------------|
|     5, 3}, {5, 1, 4}, {2, 5, 4}, {4, 5, 3}, {2, 1, 6}, {6, 1, 3}, {2, 6, 3},|
|     ------------------------------------------------------------------------|
|     {6, 1, 4}, {2, 6, 4}, {4, 6, 3}, {5, 1, 6}, {2, 5, 6}, {6, 5, 3}, {6, 5,|
|     ------------------------------------------------------------------------|
|     4}}                                                                     |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : isToricDegeneration L1                                                  |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

In the above example, we construct the Grassmannian matching field induced by
the given weight matrix. The tuples for the matching field are listed in RevLex
order. The function isToricDegeneration, checks the
equality of the matchingFieldIdeal, and the initial
ideal of the plueckerIdeal, with respect to the weight
inducing the matching field.

The second way to define a Grassmannian matching field is to list out its
tuples.

+-----------------------------------------------------+
|i5 : T = {{1,4}, {2,4}, {3,4}, {3,1}, {3,2}, {1,2}}  |
|                                                     |
|o5 = {{1, 4}, {2, 4}, {3, 4}, {3, 1}, {3, 2}, {1, 2}}|
|                                                     |
|o5 : List                                            |
+-----------------------------------------------------+
|i6 : L2 = grMatchingField(2, 4, T)                   |
|                                                     |
|o6 = Grassmannian Matching Field for Gr(2, 4)        |
|                                                     |
|o6 : GrMatchingField                                 |
+-----------------------------------------------------+
|i7 : getTuples L2                                    |
|                                                     |
|o7 = {{1, 2}, {3, 1}, {3, 2}, {1, 4}, {2, 4}, {3, 4}}|
|                                                     |
|o7 : List                                            |
+-----------------------------------------------------+
|i8 : isCoherent L2                                   |
|                                                     |
|o8 = true                                            |
+-----------------------------------------------------+
|i9 : getWeightMatrix L2                              |
|                                                     |
|o9 = | 0 0  0 0  |                                   |
|     | 0 -1 1 -2 |                                   |
|                                                     |
|              2       4                              |
|o9 : Matrix ZZ  <-- ZZ                               |
+-----------------------------------------------------+

As shown in the example above, the first argument "k" specifies the size of the
tuples. The third argument is a list of the tuples. Note that the tuples can be
supplied in any order. If the list of tuples is not correct, i.e. if some are
missing or duplicated then the function raises an error. When a Grassmannian
matching field is constructed in this way, it is not guaranteed to be coherent,
i.e., it may not be induced by a weight matrix. The function isCoherent,
checks whether the matching field is coherent and the function
getWeightMatrix, returns a weight matrix that induces
the matching field, if it exists. If the matching field is not coherent, then
these methods produce an error.

A note of caution. Two different weight matrices may induce the same matching
field so the function getWeightMatrix, may return a
weight matrix that is different to what may be expected. However, if a matching
field is defined by a weight matrix, then that weight matrix will be returned.

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * flMatchingField -- Construct a matching field for a
    partial flag variety
  * isToricDegeneration -- Does the matching field
    give rise to a toric degeneration
  * plueckerIdeal -- The Pluecker ideal of a matching
    field
  * matchingFieldIdeal -- The toric ideal of a
    matching field
  * isCoherent -- Is the matching field coherent
  * getWeightMatrix -- weight matrix that induces the
    matching field

Ways to use grMatchingField:
============================

  * "grMatchingField(Matrix)"
  * "grMatchingField(ZZ,ZZ,List)"

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

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

flMatchingField -- Construct a matching field for a partial flag variety
************************************************************************

Synopsis
========

  * Usage:
        L = flMatchingField(kList, weightMatrix)
        L = flMatchingField(kList, n, tuples)
        L = flMatchingField(weightMatrix)
  * Inputs:
      * kList, a list (Macaulay2Doc), positive integers; the sizes
        of the tuples of the flag matching field
      * n, an integer (Macaulay2Doc), positive integer; the tuples
        have entries in 1 .. n
      * weightMatrix, a matrix (Macaulay2Doc), induces the flag
        matching field
  * Outputs:
      * L, an instance of the type FlMatchingField,

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

This function is the basic constructor for matching fields for partial flag
varieties, which we simply call flag matching fields. The function outputs an
instance of type FlMatchingField, which represents the
flag matching field and stores all data related and computed about it.

There are three basic ways to define a flag matching field. The first way is to
supply a weight matrix that induces the flag matching field. This produces a
flag matching field for the full flag variety.

+------------------------------------------------------------+
|i1 : M = matrix {{0,0,0,0}, {4,2,3,1}, {10, 40, 30, 20}}    |
|                                                            |
|o1 = | 0  0  0  0  |                                        |
|     | 4  2  3  1  |                                        |
|     | 10 40 30 20 |                                        |
|                                                            |
|              3       4                                     |
|o1 : Matrix ZZ  <-- ZZ                                      |
+------------------------------------------------------------+
|i2 : L1 = flMatchingField M                                 |
|                                                            |
|o2 = Flag Matching Field for Fl(1, 2, 3; 4)                 |
|                                                            |
|o2 : FlMatchingField                                        |
+------------------------------------------------------------+
|i3 : netList getTuples L1                                   |
|                                                            |
|     +---------+---------+---------+---------+------+------+|
|o3 = |{1}      |{2}      |{3}      |{4}      |      |      ||
|     +---------+---------+---------+---------+------+------+|
|     |{1, 2}   |{1, 3}   |{3, 2}   |{1, 4}   |{2, 4}|{3, 4}||
|     +---------+---------+---------+---------+------+------+|
|     |{3, 2, 1}|{2, 4, 1}|{3, 4, 1}|{3, 2, 4}|      |      ||
|     +---------+---------+---------+---------+------+------+|
+------------------------------------------------------------+
|i4 : isToricDegeneration L1                                 |
|                                                            |
|o4 = true                                                   |
+------------------------------------------------------------+

In the above example, we construct the flag matching field for the full flag
variety induced by the given weight matrix. The tuples for the flag matching
field are listed by their size. Similarly to Grassmannian matching fields:
GrMatchingField, the function
isToricDegeneration, checks the equality of the
matchingFieldIdeal, and the initial ideal of the
plueckerIdeal, with respect to the weight of the matching field.

The second way to define a flag matching field is to supply a weight matrix and
specify the size of the sets or, in other words, specify the dimensions of the
vector spaces in the flags.

+------------------------------------------------+
|i5 : L2 = flMatchingField({1,2}, M)             |
|                                                |
|o5 = Flag Matching Field for Fl(1, 2; 4)        |
|                                                |
|o5 : FlMatchingField                            |
+------------------------------------------------+
|i6 : netList getTuples L2                       |
|                                                |
|     +------+------+------+------+------+------+|
|o6 = |{1}   |{2}   |{3}   |{4}   |      |      ||
|     +------+------+------+------+------+------+|
|     |{1, 2}|{1, 3}|{3, 2}|{1, 4}|{2, 4}|{3, 4}||
|     +------+------+------+------+------+------+|
+------------------------------------------------+

The third way to define a flag matching field is by listing out its tuples.

+-----------------------------------------------------------------------------+
|i7 : T = getTuples L1                                                        |
|                                                                             |
|o7 = {{{1}, {2}, {3}, {4}}, {{1, 2}, {1, 3}, {3, 2}, {1, 4}, {2, 4}, {3, 4}},|
|     ------------------------------------------------------------------------|
|     {{3, 2, 1}, {2, 4, 1}, {3, 4, 1}, {3, 2, 4}}}                           |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : L3 = flMatchingField({1,3}, 4, {T_0, T_2})                              |
|                                                                             |
|o8 = Flag Matching Field for Fl(1, 3; 4)                                     |
|                                                                             |
|o8 : FlMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i9 : getTuples L3                                                            |
|                                                                             |
|o9 = {{{1}, {2}, {3}, {4}}, {{3, 2, 1}, {2, 4, 1}, {3, 4, 1}, {3, 2, 4}}}    |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : isCoherent L3                                                          |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : getWeightMatrix L3                                                     |
|                                                                             |
|o11 = | 0 0 0 0  |                                                           |
|      | 0 0 1 -1 |                                                           |
|      | 0 2 2 0  |                                                           |
|                                                                             |
|               3       4                                                     |
|o11 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+

As shown in the example above, the first argument "kList" specifies the size of
the sets. The third argument is a list whose i-th entry is a list of tuples of
size "kList_i". In this example, the size of the sets are 1 and 3, which
correspond to "T_0" and "T_2". When a flag matching field is constructed in
this way, it is not guaranteed to be coherent, i.e., it may not be induced by a
weight matrix. Similarly to Grassmannian matching fields, the function
isCoherent, checks whether the matching field is coherent and the
function getWeightMatrix, returns a weight matrix that
induces the matching field, if it exists. If the matching field is not
coherent, then these methods produce an error.

A note of caution. Two different weight matrices may induce the same matching
field so the function getWeightMatrix, may return a
weight matrix that is different to what may be expected. However, if a matching
field is defined by a weight matrix, then that weight matrix will be returned.

See also
========

  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * GrMatchingField -- the class of Grassmannian
    matching fields
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * isToricDegeneration -- Does the matching field
    give rise to a toric degeneration
  * plueckerIdeal -- The Pluecker ideal of a matching
    field
  * matchingFieldIdeal -- The toric ideal of a
    matching field
  * isCoherent -- Is the matching field coherent
  * getWeightMatrix -- weight matrix that induces the
    matching field

Ways to use flMatchingField:
============================

  * "flMatchingField(List,Matrix)"
  * "flMatchingField(List,ZZ,List)"
  * "flMatchingField(Matrix)"

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

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

diagonalMatchingField -- the diagonal matching field
****************************************************

Synopsis
========

  * Usage:
        Lgr = diagonalMatchingField(k, n)
        Lfl = diagonalMatchingField(kList, n)
        Lfl = diagonalMatchingField(n)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * kList, a list (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * Lgr, an instance of the type GrMatchingField,
        diagonal Grassmannian matching field
      * Lfl, an instance of the type FlMatchingField,
        diagonal flag matching field

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

The diagonal matching field is defined to be the matching field whose tuples
are all in ascending order. It is a coherent matching field so it is induced by
a weight matrix.

The weight matrix used to construct the diagonal matching field us given by $M
= (m_{i,j})$ with $m_{i,j} = (i-1)(n-j+1)$.

+---------------------------------------------+
|i1 : L = diagonalMatchingField(3, 6)         |
|                                             |
|o1 = Grassmannian Matching Field for Gr(3, 6)|
|                                             |
|o1 : GrMatchingField                         |
+---------------------------------------------+
|i2 : getWeightMatrix L                       |
|                                             |
|o2 = | 0  0  0 0 0 0 |                       |
|     | 6  5  4 3 2 1 |                       |
|     | 12 10 8 6 4 2 |                       |
|                                             |
|              3       6                      |
|o2 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+

The function diagonalMatchingField, can be used in
three different ways. If it is supplied two integers $(k,n)$ then it produces
the diagonal matching field for the Grassmannian, as shown in the above
example. If it is supplied a single integer $n$, then it produces the diagonal
matching field for the full flag variety. The matching fields of the full flag
variety have tuples of size $1, 2, \dots, n-1$. The function can be made to
produce diagonal matching fields for partial flag varieties by supplying it a
list $kList$ and integer $n$. The sizes of the tuples are the entries of
$kList$.

+----------------------------------------------------------------------------+
|i3 : L = diagonalMatchingField 4;                                           |
+----------------------------------------------------------------------------+
|i4 : netList getTuples L                                                    |
|                                                                            |
|     +---------+---------+---------+---------+------+------+                |
|o4 = |{1}      |{2}      |{3}      |{4}      |      |      |                |
|     +---------+---------+---------+---------+------+------+                |
|     |{1, 2}   |{1, 3}   |{2, 3}   |{1, 4}   |{2, 4}|{3, 4}|                |
|     +---------+---------+---------+---------+------+------+                |
|     |{1, 2, 3}|{1, 2, 4}|{1, 3, 4}|{2, 3, 4}|      |      |                |
|     +---------+---------+---------+---------+------+------+                |
+----------------------------------------------------------------------------+
|i5 : L = diagonalMatchingField({1, 2}, 5);                                  |
+----------------------------------------------------------------------------+
|i6 : netList getTuples L                                                    |
|                                                                            |
|     +------+------+------+------+------+------+------+------+------+------+|
|o6 = |{1}   |{2}   |{3}   |{4}   |{5}   |      |      |      |      |      ||
|     +------+------+------+------+------+------+------+------+------+------+|
|     |{1, 2}|{1, 3}|{2, 3}|{1, 4}|{2, 4}|{3, 4}|{1, 5}|{2, 5}|{3, 5}|{4, 5}||
|     +------+------+------+------+------+------+------+------+------+------+|
+----------------------------------------------------------------------------+

Diagonal matching fields always give rise to toric degenerations of
Grassmannians and flag varieties. In the literature, this toric degeneration is
also known as Gelfand-Tsetlin degeneration. The matching field polytopes for
the diagonal matching field, which can be constructed with the function
matchingFieldPolytope, are unimodularly equivalent to
Gelfand-Tsetlin polytopes.

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * isToricDegeneration -- Does the matching field
    give rise to a toric degeneration
  * matchingFieldPolytope -- The polytope of a
    matching field

Ways to use diagonalMatchingField:
==================================

  * "diagonalMatchingField(List,ZZ)"
  * "diagonalMatchingField(ZZ)"
  * "diagonalMatchingField(ZZ,ZZ)"

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

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

matchingFieldFromPermutation -- matching field parametrised by permutations
***************************************************************************

Synopsis
========

  * Usage:
        Lgr = matchingFieldFromPermutation(k, n, S)
        Lfl = matchingFieldFromPermutation(kList, n, S)
  * Inputs:
      * k, an integer (Macaulay2Doc), positive integer; the size of
        the tuples of the Grassmannian matching field
      * kList, a list (Macaulay2Doc), positive integers; the sizes
        of the tuples of the flag matching field
      * n, an integer (Macaulay2Doc), positive integer; the tuples
        have entries in 1 .. n
  * Optional inputs (Macaulay2Doc),:
      * RowNum => an integer (Macaulay2Doc), default value 2, which
        row of the digonal weight matrix to permute
      * UsePrimePowers => a Boolean value (Macaulay2Doc),
        default value false, use multiples of prime power used for the entries
        of the diagonal weight matrix
      * PowerValue => an integer (Macaulay2Doc), default value 0, use
        multiples of powers this value in the diagonal weight matrix
      * ScalingCoefficient => an integer (Macaulay2Doc), default
        value 1, the value by which to scale the permuted row of the diagonal
        weight matrix
  * Outputs:
      * Lgr, an instance of the type GrMatchingField,
      * Lfl, an instance of the type FlMatchingField,

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

Let $M_0 \in \RR^{k \times n}$ be a matrix that induced the diagonal matching
field. Usually, we take this matrix to be $(m_{i,j})$ with $m_{i,j} =
(n-j)n^(i-2)$ if $i > 1$ and $m_{i,j} = 0$ if $i = 1$. Note that this matrix is
different to the weight matrix of the matching field produced by the function
diagonalMatchingField, however the matching
fields are the same. Given a permutation $\sigma \in S_n$, the matching field
associated to $\sigma$ has weight matrix $M_\sigma$, which is the same as $M_0$
except in the second row, which is given by $\sigma(1), \sigma(2), \dots,
\sigma(n)$. If $\sigma = (n, n-1, \dots, 1) \in S_n$ is the permutation written
in single-line notation, then the matching field induced by $M_\sigma$ is the
diagonal matching field.

+-----------------------------------------------------------------+
|i1 : L0 = diagonalMatchingField(3, 6)                            |
|                                                                 |
|o1 = Grassmannian Matching Field for Gr(3, 6)                    |
|                                                                 |
|o1 : GrMatchingField                                             |
+-----------------------------------------------------------------+
|i2 : getWeightMatrix L0                                          |
|                                                                 |
|o2 = | 0  0  0 0 0 0 |                                           |
|     | 6  5  4 3 2 1 |                                           |
|     | 12 10 8 6 4 2 |                                           |
|                                                                 |
|              3       6                                          |
|o2 : Matrix ZZ  <-- ZZ                                           |
+-----------------------------------------------------------------+
|i3 : L1 = matchingFieldFromPermutation(3, 6, {6,5,4,3,2,1})      |
|                                                                 |
|o3 = Grassmannian Matching Field for Gr(3, 6)                    |
|                                                                 |
|o3 : GrMatchingField                                             |
+-----------------------------------------------------------------+
|i4 : getWeightMatrix L1                                          |
|                                                                 |
|o4 = | 0  0  0  0  0 0 |                                         |
|     | 6  5  4  3  2 1 |                                         |
|     | 30 24 18 12 6 0 |                                         |
|                                                                 |
|              3       6                                          |
|o4 : Matrix ZZ  <-- ZZ                                           |
+-----------------------------------------------------------------+
|i5 : L0 == L1                                                    |
|                                                                 |
|o5 = true                                                        |
+-----------------------------------------------------------------+
|i6 : L2 = matchingFieldFromPermutation(3, 6, {1,3,2,6,4,5})      |
|                                                                 |
|o6 = Grassmannian Matching Field for Gr(3, 6)                    |
|                                                                 |
|o6 : GrMatchingField                                             |
+-----------------------------------------------------------------+
|i7 : getWeightMatrix L2                                          |
|                                                                 |
|o7 = | 0  0  0  0  0 0 |                                         |
|     | 1  3  2  6  4 5 |                                         |
|     | 30 24 18 12 6 0 |                                         |
|                                                                 |
|              3       6                                          |
|o7 : Matrix ZZ  <-- ZZ                                           |
+-----------------------------------------------------------------+
|i8 : L3 = matchingFieldFromPermutation({1,2,3}, 6, {1,4,2,3,6,5})|
|                                                                 |
|o8 = Flag Matching Field for Fl(1, 2, 3; 6)                      |
|                                                                 |
|o8 : FlMatchingField                                             |
+-----------------------------------------------------------------+
|i9 : getWeightMatrix L3                                          |
|                                                                 |
|o9 = | 0  0  0  0  0 0 |                                         |
|     | 1  4  2  3  6 5 |                                         |
|     | 30 24 18 12 6 0 |                                         |
|                                                                 |
|              3       6                                          |
|o9 : Matrix ZZ  <-- ZZ                                           |
+-----------------------------------------------------------------+

The optional argument RowNum, is used to change which row of
$M_0$ is permuted.

+-------------------------------------------------------------------------+
|i10 : L4 = matchingFieldFromPermutation(3, 6, {1,4,2,3,6,5}, RowNum => 3)|
|                                                                         |
|o10 = Grassmannian Matching Field for Gr(3, 6)                           |
|                                                                         |
|o10 : GrMatchingField                                                    |
+-------------------------------------------------------------------------+
|i11 : getWeightMatrix L4                                                 |
|                                                                         |
|o11 = | 0 0  0  0  0  0  |                                               |
|      | 5 4  3  2  1  0  |                                               |
|      | 6 24 12 18 36 30 |                                               |
|                                                                         |
|               3       6                                                 |
|o11 : Matrix ZZ  <-- ZZ                                                  |
+-------------------------------------------------------------------------+

The optional argument UsePrimePowers, is used to modify
the original diagonal weight matrix $M_0$. If the option is set to true then we
use the matrix with entries $m_{i,j} = (n-j) p^(i-2)$ if $i>1$ and $m_{i,j} =
0$ if $i = 1$, where $p \ge n$ is the smallest prime number greater than or
equal to $n$.

+-----------------------------------------------------------------------------+
|i12 : L5 = matchingFieldFromPermutation(3, 6, {1,3,2,4,6,5}, UsePrimePowers  |
|                                                                             |
|o12 = Grassmannian Matching Field for Gr(3, 6)                               |
|                                                                             |
|o12 : GrMatchingField                                                        |
|-----------------------------------------------------------------------------|
|=> true)                                                                     |
+-----------------------------------------------------------------------------+
|i13 : getWeightMatrix L5                                                     |
|                                                                             |
|o13 = | 0  0  0  0  0 0 |                                                    |
|      | 1  3  2  4  6 5 |                                                    |
|      | 35 28 21 14 7 0 |                                                    |
|                                                                             |
|               3       6                                                     |
|o13 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+

The optional argument PowerValue, is used to give a
specific value to $p$ in the diagonal weight matrix as described above. If the
value is not positive, then the argument is ignored. This option should be used
carefully. If the power value is set incorrectly (typically by setting a value
that is too low) then the weight matrix may not be generic, i.e., it does not
define a matching field. However, in such a case, the function produces a
matching field without error, as shown in the example $L7$ below. Working with
such matching fields may lead to unexpected behaviours.

+-----------------------------------------------------------------------------+
|i14 : L6 = matchingFieldFromPermutation(3, 6, {1,3,2,4,6,5}, PowerValue =>   |
|                                                                             |
|o14 = Grassmannian Matching Field for Gr(3, 6)                               |
|                                                                             |
|o14 : GrMatchingField                                                        |
|-----------------------------------------------------------------------------|
|10)                                                                          |
+-----------------------------------------------------------------------------+
|i15 : getWeightMatrix L6                                                     |
|                                                                             |
|o15 = | 0  0  0  0  0  0 |                                                   |
|      | 1  3  2  4  6  5 |                                                   |
|      | 50 40 30 20 10 0 |                                                   |
|                                                                             |
|               3       6                                                     |
|o15 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i16 : L7 = matchingFieldFromPermutation(3, 6, {5,4,3,2,1,0}, PowerValue => 1)|
|                                                                             |
|o16 = Grassmannian Matching Field for Gr(3, 6)                               |
|                                                                             |
|o16 : GrMatchingField                                                        |
+-----------------------------------------------------------------------------+
|i17 : getWeightMatrix L7                                                     |
|                                                                             |
|o17 = | 0 0 0 0 0 0 |                                                        |
|      | 5 4 3 2 1 0 |                                                        |
|      | 5 4 3 2 1 0 |                                                        |
|                                                                             |
|               3       6                                                     |
|o17 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+

Any positive integer supplied to the argument PowerValue,
takes precedence over UsePrimePowers. The optional
argument ScalingCoefficient, is used to scale the
entries of the row that is permuted by the permutation. If
UsePrimePowers, is set to true, and $p \ge n$ is the smallest
prime number less than $n$, then the scaling coefficient can be set to any $c
\in \{1, 2, \dots, p-1\}$ and the resulting weight matrix is guaranteed to be
generic.

+-----------------------------------------------------------------------------+
|i18 : L8 = matchingFieldFromPermutation(3, 6, {6,1,5,2,3,4}, UsePrimePowers  |
|                                                                             |
|o18 = Grassmannian Matching Field for Gr(3, 6)                               |
|                                                                             |
|o18 : GrMatchingField                                                        |
|-----------------------------------------------------------------------------|
|=> true, ScalingCoefficient => 3)                                            |
+-----------------------------------------------------------------------------+
|i19 : getWeightMatrix L8                                                     |
|                                                                             |
|o19 = | 0  0  0  0  0 0  |                                                   |
|      | 18 3  15 6  9 12 |                                                   |
|      | 35 28 21 14 7 0  |                                                   |
|                                                                             |
|               3       6                                                     |
|o19 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i20 : isToricDegeneration L8                                                 |
|                                                                             |
|o20 = false                                                                  |
+-----------------------------------------------------------------------------+

The above is an example of a hexagonal matching field, which does not give rise
to a toric degeneration of the Grassmannian Gr$(3, 6)$.

See also
========

  * RowNum -- the row of the diagonal weight matrix to permute
  * UsePrimePowers -- use a diagonal weight matrix with
    multiples of certain powers
  * PowerValue -- use a diagonal weight matrix with
    multiples of certain powers
  * ScalingCoefficient -- scale the permuted row of
    the weight matrix

Ways to use matchingFieldFromPermutation:
=========================================

  * "matchingFieldFromPermutation(List,ZZ,List)"
  * "matchingFieldFromPermutation(ZZ,ZZ,List)"

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

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

RowNum -- the row of the diagonal weight matrix to permute
**********************************************************

Synopsis
========

  * Usage:
        Lgr = matchingFieldFromPermutation(k, n, S, RowNum => r)
        Lfl = matchingFieldFromPermutation(kList, n, S, RowNum => r)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * kList, a list (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
      * S, a list (Macaulay2Doc), a permutation of $1, \dots, n$
      * r, an integer (Macaulay2Doc), an integer at most $k$ or at
        most $\max(kList)$
  * Outputs:
      * Lgr, an instance of the type GrMatchingField,
      * Lfl, an instance of the type FlMatchingField,

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

The option RowNum, chooses the row of the diagonal matching field
weight matrix to permute. By default the value is $2$.

+-----------------------------------------------------------------------------+
|i1 : getWeightMatrix matchingFieldFromPermutation(3, 6, {4,5,6,1,2,3}, RowNum|
|                                                                             |
|o1 = | 0  0  0  0  0 0 |                                                     |
|     | 5  4  3  2  1 0 |                                                     |
|     | 30 24 18 12 6 0 |                                                     |
|                                                                             |
|              3       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|=> 1)                                                                        |
+-----------------------------------------------------------------------------+
|i2 : getWeightMatrix matchingFieldFromPermutation(3, 6, {4,5,6,1,2,3}, RowNum|
|                                                                             |
|o2 = | 0  0  0  0  0 0 |                                                     |
|     | 4  5  6  1  2 3 |                                                     |
|     | 30 24 18 12 6 0 |                                                     |
|                                                                             |
|              3       6                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|=> 2)                                                                        |
+-----------------------------------------------------------------------------+
|i3 : getWeightMatrix matchingFieldFromPermutation(3, 6, {4,5,6,1,2,3}, RowNum|
|                                                                             |
|o3 = | 0  0  0  0 0  0  |                                                    |
|     | 5  4  3  2 1  0  |                                                    |
|     | 24 30 36 6 12 18 |                                                    |
|                                                                             |
|              3       6                                                      |
|o3 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|=> 3)                                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * matchingFieldFromPermutation, --
    matching field parametrised by permutations
  * diagonalMatchingField -- the diagonal
    matching field

Functions with optional argument named RowNum:
==============================================

  * "matchingFieldFromPermutation(...,RowNum=>...)" -- see
    matchingFieldFromPermutation, -- matching
    field parametrised by permutations

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

The object RowNum, is a symbol (Macaulay2Doc).

UsePrimePowers -- use a diagonal weight matrix with multiples of certain powers
*******************************************************************************

Synopsis
========

  * Usage:
        Lgr = matchingFieldFromPermutation(k, n, S, UsePrimePowers => b, PowerValue => v)
        Lfl = matchingFieldFromPermutation(kList, n, S, UsePrimePowers => b, PowerValue => v)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * kList, a list (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
      * S, a list (Macaulay2Doc), a permutation of $1, \dots, n$
      * r, a Boolean value (Macaulay2Doc), set whether prime
        powers are to be used
      * v, an integer (Macaulay2Doc), set the value of the powers to
        be used
  * Outputs:
      * Lgr, an instance of the type GrMatchingField,
      * Lfl, an instance of the type FlMatchingField,

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

The options UsePrimePowers, and PowerValue,
are optional arguments for the function
matchingFieldFromPermutation, which constructs a
matching field by permuting a row (usually the second row) of a weight matrix
that gives rise to the diagonal matching field.

If the option UsePrimePowers, is set to true, then the
underlying diagonal weight matrix is given by $M_0 = (m_{i,j})$ with $m_{i,j} =
(n-j) p^(i-2)$ if $i > 1$ and $m_{i,j} = 0$ if $i = 1$, where $p \ge n$ is the
smallest prime number greater than or equal to $n$.

+-----------------------------------------------------------------------------+
|i1 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1,2,3,4,5,6},       |
|                                                                             |
|o1 = | 0  0  0  0  0 0 |                                                     |
|     | 1  2  3  4  5 6 |                                                     |
|     | 30 24 18 12 6 0 |                                                     |
|                                                                             |
|              3       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|UsePrimePowers => false)                                                     |
+-----------------------------------------------------------------------------+
|i2 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1,2,3,4,5,6},       |
|                                                                             |
|o2 = | 0  0  0  0  0 0 |                                                     |
|     | 1  2  3  4  5 6 |                                                     |
|     | 35 28 21 14 7 0 |                                                     |
|                                                                             |
|              3       6                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|UsePrimePowers => true)                                                      |
+-----------------------------------------------------------------------------+

To set the value of $p$ in the above matrix to a specific value, use the option
PowerValue.

+-----------------------------------------------------------------------------+
|i3 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1,2,3,4,5,6},       |
|                                                                             |
|o3 = | 0  0  0  0  0  0 |                                                    |
|     | 1  2  3  4  5  6 |                                                    |
|     | 50 40 30 20 10 0 |                                                    |
|                                                                             |
|              3       6                                                      |
|o3 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|PowerValue => 10)                                                            |
+-----------------------------------------------------------------------------+

The option PowerValue, overrides the option
UsePrimePowers.

Warning. Certain values for the option PowerValue, will
produce weight matrices that are not generic, i.e., the initial term of the
corresponding Pluecker forms are not all monomials, hence the weight matrix
does not define a matching field. The function
matchingFieldFromPermutation, will produce a
matching field, which may lead to unexpected behaviours.

Precise details. The value of $p$ is determined as follows. The option
PowerValue, is used if it is a positive value. If
PowerValue, is not positive then the function checks to see if
the option UsePrimePowers, is set to true. If it is, then
the value of $p$ is set to be the small prime number greater than or equal to
$n$. Otherwise, if UsePrimePowers, is set to false, then
$p$ is set to be $n$.

See also
========

  * matchingFieldFromPermutation, --
    matching field parametrised by permutations
  * RowNum -- the row of the diagonal weight matrix to permute

Functions with optional argument named UsePrimePowers:
======================================================

  * "matchingFieldFromPermutation(...,UsePrimePowers=>...)" -- see
    matchingFieldFromPermutation, -- matching
    field parametrised by permutations

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

The object UsePrimePowers, is a symbol (Macaulay2Doc).

ScalingCoefficient -- scale the permuted row of the weight matrix
*****************************************************************

Synopsis
========

  * Usage:
        Lgr = matchingFieldFromPermutation(k, n, S, ScalingCoefficient => c)
        Lfl = matchingFieldFromPermutation(kList, n, S, ScalingCoefficient => c)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * kList, a list (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
      * S, a list (Macaulay2Doc), a permutation of $1, \dots, n$
      * c, an integer (Macaulay2Doc), scale the value of permuted row
        by $c$
  * Outputs:
      * Lgr, an instance of the type GrMatchingField,
      * Lfl, an instance of the type FlMatchingField,

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

The function matchingFieldFromPermutation,
constructs a weight matrix by permuting the row of a weight matrix that induces
the diagonal matching field. The option ScalingCoefficient,
sets the scaling coefficient of the row being permuted,
which by default is $1$.

Note that by setting the option UsePrimePowers, to true,
it guarantees that the weight matrix is generic, i.e., the matching field is
well defined, as long as the scaling coefficient is less than the prime power
used.

+-----------------------------------------------------------------------------+
|i1 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1, 3, 2, 4, 6, 5},  |
|                                                                             |
|o1 = | 0  0  0  0  0 0 |                                                     |
|     | 1  3  2  4  6 5 |                                                     |
|     | 35 28 21 14 7 0 |                                                     |
|                                                                             |
|              3       6                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|UsePrimePowers => true, ScalingCoefficient => 1)                             |
+-----------------------------------------------------------------------------+
|i2 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1, 3, 2, 4, 6, 5},  |
|                                                                             |
|o2 = | 0  0  0  0  0  0  |                                                   |
|     | 2  6  4  8  12 10 |                                                   |
|     | 35 28 21 14 7  0  |                                                   |
|                                                                             |
|              3       6                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|UsePrimePowers => true, ScalingCoefficient => 2)                             |
+-----------------------------------------------------------------------------+
|i3 : getWeightMatrix matchingFieldFromPermutation(3, 6, {1, 3, 2, 4, 6, 5},  |
|                                                                             |
|o3 = | 0  0  0  0  0  0  |                                                   |
|     | 3  9  6  12 18 15 |                                                   |
|     | 35 28 21 14 7  0  |                                                   |
|                                                                             |
|              3       6                                                      |
|o3 : Matrix ZZ  <-- ZZ                                                       |
|-----------------------------------------------------------------------------|
|UsePrimePowers => true, ScalingCoefficient => 3)                             |
+-----------------------------------------------------------------------------+

See also
========

  * matchingFieldFromPermutation, --
    matching field parametrised by permutations
  * RowNum -- the row of the diagonal weight matrix to permute
  * UsePrimePowers -- use a diagonal weight matrix with
    multiples of certain powers

Functions with optional argument named ScalingCoefficient:
==========================================================

  * "matchingFieldFromPermutation(...,ScalingCoefficient=>...)" -- see
    matchingFieldFromPermutation, -- matching
    field parametrised by permutations

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

The object ScalingCoefficient, is a symbol (Macaulay2Doc).

getTuples -- The tuples of a matching field
*******************************************

Synopsis
========

  * Usage:
        tuples = getTuples L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * tuples, a list (Macaulay2Doc), A list of subsets of $1,
        \dots, n$; the tuples of the matching field

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

A matching field $\Lambda$ for the Grassmannian Gr$(k, n)$ is a collection
tuples $\Lambda(J)$ for each $k$-subset $J \subseteq [n]$. The entries of the
tuple form a permutation of $J$, so in some literature $\Lambda(J)$ is taken to
be the element of the symmetric group $\sigma \in S_k$ such that $\Lambda(J) =
(j_{\sigma(1)}, j_{\sigma(2), \dots, j_{\sigma(k)}})$ where $J = \{j_1 < j_2 <
\dots < j_k\}$.

+-----------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                 |
|                                                     |
|o1 = Grassmannian Matching Field for Gr(2, 4)        |
|                                                     |
|o1 : GrMatchingField                                 |
+-----------------------------------------------------+
|i2 : getTuples L                                     |
|                                                     |
|o2 = {{1, 2}, {1, 3}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}|
|                                                     |
|o2 : List                                            |
+-----------------------------------------------------+

The tuples are stored such that their underlying sets are in RevLex order,
which is the order produced by the method subsets (Macaulay2Doc).

For flag matching fields, the tuples are stored as a list of list of tuples for
each Grassmannian matching field contained within.

+------------------------------------------------+
|i3 : L = diagonalMatchingField({1,2}, 4)        |
|                                                |
|o3 = Flag Matching Field for Fl(1, 2; 4)        |
|                                                |
|o3 : FlMatchingField                            |
+------------------------------------------------+
|i4 : netList getTuples L                        |
|                                                |
|     +------+------+------+------+------+------+|
|o4 = |{1}   |{2}   |{3}   |{4}   |      |      ||
|     +------+------+------+------+------+------+|
|     |{1, 2}|{1, 3}|{2, 3}|{1, 4}|{2, 4}|{3, 4}||
|     +------+------+------+------+------+------+|
+------------------------------------------------+

See also
========

  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * flMatchingField -- Construct a matching field for a
    partial flag variety
  * diagonalMatchingField -- the diagonal
    matching field

Ways to use getTuples:
======================

  * "getTuples(FlMatchingField)"
  * "getTuples(GrMatchingField)"
  * getTuples(TopeField) -- tuples of a tope
    field

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

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

getGrMatchingFields -- The Grassmannian matching fields of a Flag matching field
********************************************************************************

Synopsis
========

  * Usage:
        matchingFieldList = getGrMatchingFields L
  * Inputs:
      * L, an instance of the type FlMatchingField,
  * Outputs:
      * matchingFieldList, a list (Macaulay2Doc), The Grassmannian
        matching fields contained in L.

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

This function returns a list of the GrMatchingField,s
that are contained within the given FlMatchingField.

+-----------------------------------------------+
|i1 : D = diagonalMatchingField({1,2,3}, 6);    |
+-----------------------------------------------+
|i2 : getWeightMatrix D                         |
|                                               |
|o2 = | 0  0  0 0 0 0 |                         |
|     | 6  5  4 3 2 1 |                         |
|     | 12 10 8 6 4 2 |                         |
|                                               |
|              3       6                        |
|o2 : Matrix ZZ  <-- ZZ                         |
+-----------------------------------------------+
|i3 : netList getGrMatchingFields D             |
|                                               |
|     +----------------------------------------+|
|o3 = |Grassmannian Matching Field for Gr(1, 6)||
|     +----------------------------------------+|
|     |Grassmannian Matching Field for Gr(2, 6)||
|     +----------------------------------------+|
|     |Grassmannian Matching Field for Gr(3, 6)||
|     +----------------------------------------+|
+-----------------------------------------------+
|i4 : D2 = (getGrMatchingFields D)_1;           |
+-----------------------------------------------+
|i5 : getWeightMatrix D2                        |
|                                               |
|o5 = | 0 0 0 0 0 0 |                           |
|     | 6 5 4 3 2 1 |                           |
|                                               |
|              2       6                        |
|o5 : Matrix ZZ  <-- ZZ                         |
+-----------------------------------------------+

The above example constructs the diagonal matching field for the partial flag
variety Fl(123; 6), which contains the data for three distinct Grassmannian
matching fields. Each GrMatchingField, is a diagonal
matching field, which are induced by a submatrix of the original weight matrix
that induces the flag matching field.

Ways to use getGrMatchingFields:
================================

  * "getGrMatchingFields(FlMatchingField)"

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

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

isCoherent -- Is the matching field coherent
********************************************

Synopsis
========

  * Usage:
        result = isCoherent L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), is the matching
        field coherent, i.e., induced by a weight matrix

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

We say that a matching field $\Lambda$ is coherent if it is induced by a weight
matrix. Note that we use the minimum convention for weight matrices however for
polynomial rings, the Weights (Macaulay2Doc), option for
MonomialOrder (Macaulay2Doc), uses the maximum convention.

+---------------------------------------------------------------------------+
|i1 : L1 = grMatchingField(2, 4, {{1,2}, {1,3}, {2,3}, {1,4}, {2,4}, {4,3}})|
|                                                                           |
|o1 = Grassmannian Matching Field for Gr(2, 4)                              |
|                                                                           |
|o1 : GrMatchingField                                                       |
+---------------------------------------------------------------------------+
|i2 : isCoherent L1                                                         |
|                                                                           |
|o2 = true                                                                  |
+---------------------------------------------------------------------------+
|i3 : getWeightMatrix L1                                                    |
|                                                                           |
|o3 = | 0 0  0  0  |                                                        |
|     | 0 -1 -3 -2 |                                                        |
|                                                                           |
|              2       4                                                    |
|o3 : Matrix ZZ  <-- ZZ                                                     |
+---------------------------------------------------------------------------+
|i4 : L2 = grMatchingField(2, 3, {{1,2}, {2,3}, {3,1}})                     |
|                                                                           |
|o4 = Grassmannian Matching Field for Gr(2, 3)                              |
|                                                                           |
|o4 : GrMatchingField                                                       |
+---------------------------------------------------------------------------+
|i5 : isCoherent L2                                                         |
|                                                                           |
|o5 = false                                                                 |
+---------------------------------------------------------------------------+

In the examples above, the matching fields are defined in terms of their
tuples. To check whether the matching fields are coherent, the weight matrix
cone is constructed, see the function weightMatrixCone.
The matching field is coherent if and only if the weight
matrix cone is full dimensional. If the matching field happens to be coherent,
then an interior point is used for any further computations that require a
weight matrix.

See also
========

  * weightMatrixCone -- The cone of weight matrices
    that induce the matching field

Ways to use isCoherent:
=======================

  * "isCoherent(FlMatchingField)"
  * "isCoherent(GrMatchingField)"

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

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

getWeightMatrix -- weight matrix that induces the matching field
****************************************************************

Synopsis
========

  * Usage:
        M = getWeightMatrix L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * M, a matrix (Macaulay2Doc), weight matrix that induces
        the matching field

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

If the supplied matching field is coherent, then this function returns a weight
matrix that induces the matching field. If the matching field was originally
defined by a weight matrix then that weight matrix is returned. Otherwise, a
weight matrix is computed. The weight matrix is computed by computing the
weight matrix cone, which can be returned with the function
weightMatrixCone. If the supplied matching field is not
coherent, then the function gives an error.

+--------------------------------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                                      |
|                                                                          |
|o1 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o1 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i2 : getWeightMatrix L                                                    |
|                                                                          |
|o2 = | 0 0 0 0 |                                                          |
|     | 4 3 2 1 |                                                          |
|                                                                          |
|              2       4                                                   |
|o2 : Matrix ZZ  <-- ZZ                                                    |
+--------------------------------------------------------------------------+
|i3 : L = grMatchingField(2, 4, {{1,2}, {1,3}, {3,2}, {1,4}, {4,2}, {3,4}})|
|                                                                          |
|o3 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o3 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i4 : isCoherent L                                                         |
|                                                                          |
|o4 = true                                                                 |
+--------------------------------------------------------------------------+
|i5 : getWeightMatrix L                                                    |
|                                                                          |
|o5 = | 0 0  0  0  |                                                       |
|     | 0 -3 -1 -2 |                                                       |
|                                                                          |
|              2       4                                                   |
|o5 : Matrix ZZ  <-- ZZ                                                    |
+--------------------------------------------------------------------------+

The weight on the ring containing the Pluecker forms, i.e., minors of a generic
matrix, is based on the weight matrix returned by getWeightMatrix.
Note that the package MatchingFields, uses the
minimum convention but polynomial ring weight vectors use the maximum
convention so some conversion is required.

+-----------------------------------------------------------------------------+
|i6 : plueckerMap L                                                           |
|                                                                             |
|o6 = map (QQ[x   ..x   ], QQ[p   ..p   , p   , p   , p   , p   ], {x   x    -|
|              1,1   2,4       1,2   1,3   2,3   1,4   2,4   3,4     1,1 2,2  |
|                                                                             |
|o6 : RingMap QQ[x   ..x   ] <-- QQ[p   ..p   , p   , p   , p   , p   ]       |
|                 1,1   2,4          1,2   1,3   2,3   1,4   2,4   3,4        |
|-----------------------------------------------------------------------------|
|x   x   , x   x    - x   x   , - x   x    + x   x   , x   x    - x   x   , - |
| 1,2 2,1   1,1 2,3    1,3 2,1     1,3 2,2    1,2 2,3   1,1 2,4    1,4 2,1    |
|-----------------------------------------------------------------------------|
|x   x    + x   x   , x   x    - x   x   })                                   |
| 1,4 2,2    1,2 2,4   1,3 2,4    1,4 2,3                                     |
+-----------------------------------------------------------------------------+
|i7 : R = target plueckerMap L                                                |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : describe R                                                              |
|                                                                             |
|o8 = QQ[x   ..x   , Degrees => {8:1}, Heft => {1}, MonomialOrder =>          |
|         1,1   2,4                                                           |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32       }]                                                 |
|{Weights => {5:0, 3, 1..2}}                                                  |
|{GRevLex => {8:1}         }                                                  |
|{Position => Up           }                                                  |
+-----------------------------------------------------------------------------+

See also
========

  * getWeightPluecker -- weight of the Pluecker
    variables induced by the weight matrix
  * plueckerMap -- The ring map of the Pluecker embedding
  * weightMatrixCone -- The cone of weight matrices
    that induce the matching field

Ways to use getWeightMatrix:
============================

  * "getWeightMatrix(FlMatchingField)"
  * "getWeightMatrix(GrMatchingField)"

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

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

getWeightPluecker -- weight of the Pluecker variables induced by the weight matrix
**********************************************************************************

Synopsis
========

  * Usage:
        W = getWeightPluecker L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * W, a list (Macaulay2Doc), weights of the Pluecker variables
        induced by the matching field

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

Suppose that a coherent matching field is induced by a $k \times n$ weight
matrix $M$. The Pluecker forms are minors of a generic matrix of variables. For
example, for the Grassmannian the Pluecker forms are the maximal minors. The
weight matrix $M$ is generic, which is equivalent to the property: the initial
form of each Pluecker form with respect to $M$ is a monomial. The weight of the
initial term of each Pluecker form is the induced weight on the ring in the
Pluecker variables, which is given by the function getWeightPluecker.
By convention, the Pluecker variables are listed such that
their subsets are in RevLex order, which is the order given by the function
subsets (Macaulay2Doc).

An equivalent formulation is: the Pluecker weight vector is the tuple of
tropical determinants of $M$, also known as the image of $M$ under the tropical
Stiefel map (or its natural generalisation to partial flag varieties).

+---------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)         |
|                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)|
|                                             |
|o1 : GrMatchingField                         |
+---------------------------------------------+
|i2 : getWeightMatrix L                       |
|                                             |
|o2 = | 0 0 0 0 |                             |
|     | 4 3 2 1 |                             |
|                                             |
|              2       4                      |
|o2 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
|i3 : getWeightPluecker L                     |
|                                             |
|o3 = {3, 2, 2, 1, 1, 1}                      |
|                                             |
|o3 : List                                    |
+---------------------------------------------+

Note that the polynomial rings associated to a matching field have weight
vectors based on the weight matrix given by getWeightMatrix,
and weight vector given by getWeightPluecker.
The package MatchingFields, uses a minimum
convention but the initial terms of polynomials uses the maximum convention so
the weight vectors may look a little different.

+-----------------------------------------------------------------------------+
|i4 : m = matchingFieldRingMap L                                              |
|                                                                             |
|o4 = map (QQ[x   ..x   ], QQ[p   ..p   , p   , p   , p   , p   ], {x   x   , |
|              1,1   2,4       1,2   1,3   2,3   1,4   2,4   3,4     1,1 2,2  |
|                                                                             |
|o4 : RingMap QQ[x   ..x   ] <-- QQ[p   ..p   , p   , p   , p   , p   ]       |
|                 1,1   2,4          1,2   1,3   2,3   1,4   2,4   3,4        |
|-----------------------------------------------------------------------------|
|x   x   , x   x   , x   x   , x   x   , x   x   })                           |
| 1,1 2,3   1,2 2,3   1,1 2,4   1,2 2,4   1,3 2,4                             |
+-----------------------------------------------------------------------------+
|i5 : describe source m                                                       |
|                                                                             |
|o5 = QQ[p   ..p   , p   , p   , p   , p   , Degrees => {6:1}, Heft => {1},   |
|         1,2   1,3   2,3   1,4   2,4   3,4                                   |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32          }]                             |
|                 {Weights => {0..1, 1..2, 2:2}}                              |
|                 {GRevLex => {6:1}            }                              |
|                 {Position => Up              }                              |
+-----------------------------------------------------------------------------+
|i6 : describe target m                                                       |
|                                                                             |
|o6 = QQ[x   ..x   , Degrees => {8:1}, Heft => {1}, MonomialOrder =>          |
|         1,1   2,4                                                           |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32    }]                                                    |
|{Weights => {5:0, 1..3}}                                                     |
|{GRevLex => {8:1}      }                                                     |
|{Position => Up        }                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * getWeightMatrix -- weight matrix that induces the
    matching field
  * matchingFieldRingMap -- monomial map of the
    matching field

Ways to use getWeightPluecker:
==============================

  * "getWeightPluecker(FlMatchingField)"
  * "getWeightPluecker(GrMatchingField)"

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

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

isToricDegeneration -- Does the matching field give rise to a toric degeneration
********************************************************************************

Synopsis
========

  * Usage:
        result = isToricDegeneration L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), does the
        matching field give rise to a toric degeneration

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

A matching field is said to give rise to a toric degeneration (of the
corresponding variety: Grassmannian or partial flag variety) if the matching
field ideal is equal to the initial ideal of the Pluecker ideal with respect
the weight order that induces the matching field. For further details on each
of these ideals see the functions matchingFieldIdeal,
and plueckerIdeal.

+----------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                |
|                                                    |
|o1 = Grassmannian Matching Field for Gr(2, 4)       |
|                                                    |
|o1 : GrMatchingField                                |
+----------------------------------------------------+
|i2 : I = plueckerIdeal L                            |
|                                                    |
|o2 = ideal(p   p    - p   p    + p   p   )          |
|            2,3 1,4    1,3 2,4    1,2 3,4           |
|                                                    |
|o2 : Ideal of QQ[p   ..p   , p   , p   , p   , p   ]|
|                  1,2   1,3   2,3   1,4   2,4   3,4 |
+----------------------------------------------------+
|i3 : J = matchingFieldIdeal L                       |
|                                                    |
|o3 = ideal(p   p    - p   p   )                     |
|            2,3 1,4    1,3 2,4                      |
|                                                    |
|o3 : Ideal of QQ[p   ..p   , p   , p   , p   , p   ]|
|                  1,2   1,3   2,3   1,4   2,4   3,4 |
+----------------------------------------------------+
|i4 : J == ideal leadTerm(1, I)                      |
|                                                    |
|o4 = true                                           |
+----------------------------------------------------+
|i5 : isToricDegeneration L                          |
|                                                    |
|o5 = true                                           |
+----------------------------------------------------+

In the above example, the last two tests are the same.

If the matching field provided is not defined in terms of a weight matrix then
one is automatically computed for it. If the matching field is not coherent
then this will produce an error.

See also
========

  * matchingFieldIdeal -- The toric ideal of a
    matching field
  * plueckerIdeal -- The Pluecker ideal of a matching
    field

Ways to use isToricDegeneration:
================================

  * "isToricDegeneration(FlMatchingField)"
  * "isToricDegeneration(GrMatchingField)"

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

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

net(GrMatchingField) -- display a matching field
************************************************

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * a net (Macaulay2Doc),

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

The net (Macaulay2Doc), of a matching field displays $k$ or $kList$
and $n$ for that matching field. See GrMatchingField,
and FlMatchingField.

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties

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

  * "net(FlMatchingField)"
  * net(GrMatchingField) -- display a matching
    field

GrMatchingField == GrMatchingField -- equality of Grassmannian matching fields
******************************************************************************

Synopsis
========

  * Operator: == (Macaulay2Doc),
  * Usage:
        result = L1 == L2
  * Inputs:
      * L1, an instance of the type GrMatchingField,
      * L2, an instance of the type GrMatchingField,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), are the matching
        fields equal

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

Two matching fields are said to be equal if their tuples are equal.

+----------------------------------------------------------------------+
|i1 : L1 = diagonalMatchingField(2, 4)                                 |
|                                                                      |
|o1 = Grassmannian Matching Field for Gr(2, 4)                         |
|                                                                      |
|o1 : GrMatchingField                                                  |
+----------------------------------------------------------------------+
|i2 : getWeightMatrix L1                                               |
|                                                                      |
|o2 = | 0 0 0 0 |                                                      |
|     | 4 3 2 1 |                                                      |
|                                                                      |
|              2       4                                               |
|o2 : Matrix ZZ  <-- ZZ                                                |
+----------------------------------------------------------------------+
|i3 : getTuples L1                                                     |
|                                                                      |
|o3 = {{1, 2}, {1, 3}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}                 |
|                                                                      |
|o3 : List                                                             |
+----------------------------------------------------------------------+
|i4 : L2 = grMatchingField matrix {{0,0,0,0}, {8,4,2,1}}               |
|                                                                      |
|o4 = Grassmannian Matching Field for Gr(2, 4)                         |
|                                                                      |
|o4 : GrMatchingField                                                  |
+----------------------------------------------------------------------+
|i5 : getWeightMatrix L2                                               |
|                                                                      |
|o5 = | 0 0 0 0 |                                                      |
|     | 8 4 2 1 |                                                      |
|                                                                      |
|              2       4                                               |
|o5 : Matrix ZZ  <-- ZZ                                                |
+----------------------------------------------------------------------+
|i6 : getTuples L2                                                     |
|                                                                      |
|o6 = {{1, 2}, {1, 3}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}                 |
|                                                                      |
|o6 : List                                                             |
+----------------------------------------------------------------------+
|i7 : L1 == L2                                                         |
|                                                                      |
|o7 = true                                                             |
+----------------------------------------------------------------------+
|i8 : L3 = grMatchingField(2, 4, {{3,4},{2,4},{1,4},{2,3},{1,3},{1,2}})|
|                                                                      |
|o8 = Grassmannian Matching Field for Gr(2, 4)                         |
|                                                                      |
|o8 : GrMatchingField                                                  |
+----------------------------------------------------------------------+
|i9 : L3 == L1                                                         |
|                                                                      |
|o9 = true                                                             |
+----------------------------------------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * getTuples -- The tuples of a matching field
  * getWeightMatrix -- weight matrix that induces the
    matching field

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

  * GrMatchingField == GrMatchingField
    -- equality of Grassmannian matching fields

FlMatchingField == FlMatchingField -- equality of flag matching fields
**********************************************************************

Synopsis
========

  * Operator: == (Macaulay2Doc),
  * Usage:
        result = L1 == L2
  * Inputs:
      * L1, an instance of the type FlMatchingField,
      * L2, an instance of the type FlMatchingField,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), are the flag
        matching fields equal

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

Two matching fields are said to be equal if their tuples are equal. In the case
of flag matching fields, the $kList$s must be equal.

+-----------------------------------------------------------------------------+
|i1 : L1 = diagonalMatchingField({1,2}, 4)                                    |
|                                                                             |
|o1 = Flag Matching Field for Fl(1, 2; 4)                                     |
|                                                                             |
|o1 : FlMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i2 : getWeightMatrix L1                                                      |
|                                                                             |
|o2 = | 0 0 0 0 |                                                             |
|     | 4 3 2 1 |                                                             |
|                                                                             |
|              2       4                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : getTuples L1                                                            |
|                                                                             |
|o3 = {{{1}, {2}, {3}, {4}}, {{1, 2}, {1, 3}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}}|
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : L2 = flMatchingField({1,2}, matrix {{0,0,0,0}, {8,4,2,1}})              |
|                                                                             |
|o4 = Flag Matching Field for Fl(1, 2; 4)                                     |
|                                                                             |
|o4 : FlMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i5 : getWeightMatrix L2                                                      |
|                                                                             |
|o5 = | 0 0 0 0 |                                                             |
|     | 8 4 2 1 |                                                             |
|                                                                             |
|              2       4                                                      |
|o5 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i6 : getTuples L2                                                            |
|                                                                             |
|o6 = {{{1}, {2}, {3}, {4}}, {{1, 2}, {1, 3}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}}|
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : L1 == L2                                                                |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : L3 = flMatchingField({1,2}, 4, {{{1}, {4}, {3}, {2}},                   |
|                                                                             |
|o8 = Flag Matching Field for Fl(1, 2; 4)                                     |
|                                                                             |
|o8 : FlMatchingField                                                         |
|-----------------------------------------------------------------------------|
|{{3,4},{2,4},{1,4},{2,3},{1,3},{1,2}}})                                      |
+-----------------------------------------------------------------------------+
|i9 : L3 == L1                                                                |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * getTuples -- The tuples of a matching field
  * getWeightMatrix -- weight matrix that induces the
    matching field

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

  * FlMatchingField == FlMatchingField
    -- equality of flag matching fields

plueckerIdeal -- The Pluecker ideal of a matching field
*******************************************************

Synopsis
========

  * Usage:
        I = plueckerIdeal Lgr
        I = plueckerIdeal Lfl
        I = Grassmannian Lgr
  * Inputs:
      * Lgr, an instance of the type GrMatchingField,
      * Lfl, an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a string (Macaulay2Doc), default value
        "default", either "default" or "none" (supply "none" only if $L$ is not
        coherent)
  * Outputs:
      * I, an ideal (Macaulay2Doc), The Pluecker ideal associated
        to the corresponding Grassmannian or partial flag variety with the
        correct term order given by a weight that induced the matching field

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

The Pluecker ideal is the defining ideal of a partial flag variety embedded in
a product of Grassmannians, where each Grassmannian is embedded, by the
Pluecker embedding, into a suitable projective space. In the case of the
Grassmannian Gr($k$, $n$), it is concretely given by kernel of the ring map
$K[P_I : I \subseteq [n],\  |I| = k] \rightarrow K[x_{i,j} : i \in [k], \ j \in
[n]]$ where $P_I$ is mapped to the $k \times k$ maximal minor of the matrix
$(x_{i,j})$ whose columns are indexed by the set $I$. It is well-known that
this ideal has a Groebner basis consisting of homogeneous quadrics.

The function plueckerIdeal, takes a matching field, either
for the Grassmannian or a partial flag variety and outputs the Pluecker ideal
for that Grassmannian or partial flag variety. The ambient polynomial ring that
contains this ideal is constructed to have the term order induced by the
matching field.

+--------------------------------------------------------------------------+
|i1 : L = grMatchingField(2, 4, {{1,2}, {1,3}, {1,4}, {2,3}, {2,4}, {3,4}})|
|                                                                          |
|o1 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o1 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i2 : I = plueckerIdeal L                                                  |
|                                                                          |
|o2 = ideal(p   p    - p   p    + p   p   )                                |
|            2,3 1,4    1,3 2,4    1,2 3,4                                 |
|                                                                          |
|o2 : Ideal of QQ[p   ..p   , p   , p   , p   , p   ]                      |
|                  1,2   1,3   2,3   1,4   2,4   3,4                       |
+--------------------------------------------------------------------------+
|i3 : (monoid ring I).Options.MonomialOrder                                |
|                                                                          |
|o3 = {MonomialSize => 32           }                                      |
|     {Weights => {0, 1, 1, 2, 2, 2}}                                      |
|     {GRevLex => {1, 1, 1, 1, 1, 1}}                                      |
|     {Position => Up               }                                      |
|                                                                          |
|o3 : VerticalList                                                         |
+--------------------------------------------------------------------------+
|i4 : getWeightPluecker L                                                  |
|                                                                          |
|o4 = {-1, -2, -2, -3, -3, -3}                                             |
|                                                                          |
|o4 : List                                                                 |
+--------------------------------------------------------------------------+

In the above example, the weights for the ambient ring are not the same as the
Pluecker weights of the matching field. This is because of the minimum-maximum
convention problem. For compatibility with packages such as Tropical,
we use the minimum convention in MatchingFields, so
the smallest weight with respect to the weight matrix that induces the matching
field is the initial term of a Pluecker form. However, the monomial ordering
given by Weights (Macaulay2Doc), uses the maximum convention, so
the ambient ring has weights that are based on the negative of the induced
Pluecker Weight.

Note that the given matching field must be coherent. If the matching field is
not defined in terms of a weight matrix, then the function will attempt to
compute a weight matrix for the matching field. If the matching field is not
coherent then the function will produce an error.

+--------------------------------------------------------------------------+
|i5 : L = grMatchingField(2, 4, {{1,2}, {1,3}, {4,1}, {2,3}, {2,4}, {3,4}})|
|                                                                          |
|o5 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o5 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i6 : isCoherent L                                                         |
|                                                                          |
|o6 = false                                                                |
+--------------------------------------------------------------------------+

To construct the pluecker ideal for a non-coherent matching field, set the
option MonomialOrder to "none". The resulting ideal is constructed in a
polynomial ring with the GRevLex (Macaulay2Doc), order.

+----------------------------------------------------+
|i7 : I = plueckerIdeal(L, MonomialOrder => "none")  |
|                                                    |
|o7 = ideal(p   p    - p   p    + p   p   )          |
|            2,3 1,4    1,3 2,4    1,2 3,4           |
|                                                    |
|o7 : Ideal of QQ[p   ..p   , p   , p   , p   , p   ]|
|                  1,2   1,3   2,3   1,4   2,4   3,4 |
+----------------------------------------------------+

See also
========

  * matchingFieldIdeal -- The toric ideal of a
    matching field

Ways to use plueckerIdeal:
==========================

  * "plueckerIdeal(FlMatchingField)"
  * "plueckerIdeal(GrMatchingField)"

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

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

matchingFieldIdeal -- The toric ideal of a matching field
*********************************************************

Synopsis
========

  * Usage:
        I = matchingFieldIdeal L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a string (Macaulay2Doc), default value
        "4ti2", either "M2" or "4ti2" the strategy for computing the generators
      * MonomialOrder => a string (Macaulay2Doc), default value
        "default", either "default" or "none" (supply "none" only if $L$ is not
        coherent)
  * Outputs:
      * I, an ideal (Macaulay2Doc), toric ideal of the matching
        field

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

A matching field $\Lambda$ for the Grassmannian Gr$(k,n)$ associates to each
subset $J = \{j_1 < \dots < j_k\}$ an ordering of that subset $\Lambda(J) =
(j_{\sigma(1)}, \dots, j_{\sigma(k)})$ for some permutation $\sigma \in S_k$.
The monomial map associated to a matching field $\Lambda$ is defined as the map
that sends each Pluecker coordinate $p_J$ to the monomial sgn$(\sigma)x_{1,
\Lambda(J)_1} x_{2, \Lambda(J)_2} \cdots x_{k, \Lambda(J)_k}$ where
sgn$(\sigma) \in \{+1, -1\}$ is the sign of the permutation. The matching field
ideal is the kernel of this monomial map.

+-----------------------------------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                                         |
|                                                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)                                |
|                                                                             |
|o1 : GrMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i2 : m = matchingFieldRingMap L                                              |
|                                                                             |
|o2 = map (QQ[x   ..x   ], QQ[p   ..p   , p   , p   , p   , p   ], {x   x   , |
|              1,1   2,4       1,2   1,3   2,3   1,4   2,4   3,4     1,1 2,2  |
|                                                                             |
|o2 : RingMap QQ[x   ..x   ] <-- QQ[p   ..p   , p   , p   , p   , p   ]       |
|                 1,1   2,4          1,2   1,3   2,3   1,4   2,4   3,4        |
|-----------------------------------------------------------------------------|
|x   x   , x   x   , x   x   , x   x   , x   x   })                           |
| 1,1 2,3   1,2 2,3   1,1 2,4   1,2 2,4   1,3 2,4                             |
+-----------------------------------------------------------------------------+
|i3 : I = matchingFieldIdeal L                                                |
|                                                                             |
|o3 = ideal(p   p    - p   p   )                                              |
|            2,3 1,4    1,3 2,4                                               |
|                                                                             |
|o3 : Ideal of QQ[p   ..p   , p   , p   , p   , p   ]                         |
|                  1,2   1,3   2,3   1,4   2,4   3,4                          |
+-----------------------------------------------------------------------------+
|i4 : ker m === I                                                             |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

The analogous setup holds for flag matching fields. A flag matching field can
be thought of as a union of Grassmannian matching fields. The inclusion of the
Grassmannian matching field naturally extends to an inclusion of the
corresponding ideals. The flag matching field ideals are also generated by
'incident relations' that involve Pluecker coordinates from distinct pairs of
Grassmannians within the flag variety.

+-----------------------------------------------------------------------------+
|i5 : L = diagonalMatchingField({1,2}, 4)                                     |
|                                                                             |
|o5 = Flag Matching Field for Fl(1, 2; 4)                                     |
|                                                                             |
|o5 : FlMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i6 : I = matchingFieldIdeal L                                                |
|                                                                             |
|o6 = ideal (p p    - p p   , p p    - p p   , p p    - p p   , p p    -      |
|             3 1,4    1 3,4   2 1,4    1 2,4   2 1,3    1 2,3   3 2,4        |
|     ------------------------------------------------------------------------|
|     p p   , p   p    - p   p   )                                            |
|      2 3,4   2,3 1,4    1,3 2,4                                             |
|                                                                             |
|o6 : Ideal of QQ[p ..p , p   ..p   , p   , p   , p   , p   ]                 |
|                  1   4   1,2   1,3   2,3   1,4   2,4   3,4                  |
+-----------------------------------------------------------------------------+

The functions matchingFieldIdeal, and
plueckerIdeal, both construct ideals that belong to the same
polynomial ring. Similarly, the ring maps constructed by the function
plueckerMap, and matchingFieldRingMap,
have the same target ring.

+-----------------------------------------------------------------------------+
|i7 : I' = plueckerIdeal L                                                    |
|                                                                             |
|o7 = ideal (p   p    - p   p    + p   p   , - p   p    + p   p    - p   p   ,|
|             2,3 1,4    1,3 2,4    1,2 3,4     2,3 1,4    1,3 2,4    1,2 3,4 |
|     ------------------------------------------------------------------------|
|     p   p    - p   p    + p   p   , - p   p    + p   p    - p   p   , -     |
|      2,3 1,4    1,3 2,4    1,2 3,4     2,3 1,4    1,3 2,4    1,2 3,4        |
|     ------------------------------------------------------------------------|
|     p p    + p p    + p p   , - p p    + p p    + p p   , - p p    + p p    |
|      2 1,3    1 2,3    3 1,2     2 1,4    1 2,4    4 1,2     3 1,4    1 3,4 |
|     ------------------------------------------------------------------------|
|     + p p   , - p p    + p p    + p p   )                                   |
|        4 1,3     3 2,4    2 3,4    4 2,3                                    |
|                                                                             |
|o7 : Ideal of QQ[p ..p , p   ..p   , p   , p   , p   , p   ]                 |
|                  1   4   1,2   1,3   2,3   1,4   2,4   3,4                  |
+-----------------------------------------------------------------------------+
|i8 : ring I === ring I'                                                      |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+
|i9 : source plueckerMap L                                                    |
|                                                                             |
|o9 = QQ[p ..p , p   ..p   , p   , p   , p   , p   ]                          |
|         1   4   1,2   1,3   2,3   1,4   2,4   3,4                           |
|                                                                             |
|o9 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i10 : source plueckerMap L === source matchingFieldRingMap L                 |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : target plueckerMap L                                                   |
|                                                                             |
|o11 = QQ[x   ..x   ]                                                         |
|          1,1   2,4                                                          |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : target plueckerMap L === target matchingFieldRingMap L                 |
|                                                                             |
|o12 = true                                                                   |
+-----------------------------------------------------------------------------+

If the matching field is not coherent, then the matching field ideal can be
constructed by setting the option MonomialOrder to "none". Doing this sets the
monomial order of the target polynomial ring above to GRevLex (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i13 : L = grMatchingField(2, 5, {{2,1}, {3,2}, {4,3}, {1,4}, {2,4}, {1,3},   |
|                                                                             |
|o13 = Grassmannian Matching Field for Gr(2, 5)                               |
|                                                                             |
|o13 : GrMatchingField                                                        |
|-----------------------------------------------------------------------------|
|{1,5}, {5,2}, {3,5}, {4,5}})                                                 |
+-----------------------------------------------------------------------------+
|i14 : isCoherent L                                                           |
|                                                                             |
|o14 = false                                                                  |
+-----------------------------------------------------------------------------+
|i15 : I = matchingFieldIdeal(L, MonomialOrder => "none")                     |
|                                                                             |
|o15 = ideal(- p   p    - p   p   )                                           |
|               3,4 1,5    1,3 4,5                                            |
|                                                                             |
|o15 : Ideal of QQ[p   ..p   , p   , p   , p   , p   , p   , p   , p   , p   ]|
|                   1,2   1,3   2,3   1,4   2,4   3,4   1,5   2,5   3,5   4,5 |
+-----------------------------------------------------------------------------+
|i16 : (options ring I).MonomialOrder                                         |
|                                                                             |
|o16 = {MonomialSize => 32                       }                            |
|      {GRevLex => {1, 1, 1, 1, 1, 1, 1, 1, 1, 1}}                            |
|      {Position => Up                           }                            |
|                                                                             |
|o16 : VerticalList                                                           |
+-----------------------------------------------------------------------------+

The option Strategy (Macaulay2Doc), determines how the matching
field ideal is computed. The default uses the package FourTiTwo.
This strategy works by passing in the matrix of the toric
ideal to toricGroebner (FourTiTwo), with the correct weight
vector. In the case of Grassmannian matching fields, the columns of the matrix
of the toric ideal are exactly the vertices of the matching field polytope. For
a flag matching field $\Lambda$, the matrix of the toric ideal is the
top-justified juxtaposition of such matrices for the Grassmannian matching
fields contained in $\Lambda$. On the other hand, the strategy "M2" simply uses
the in-built function to compute the kernel of the map
matchingFieldRingMap.

Caveat
======

For some versions of the package FourTiTwo, the strategy
"4ti2" may not correctly take into account the weights. See the caveat in the
documentation of the function toricGroebner (FourTiTwo).
If there are any problems, it may be more reliable to use the option "M2".

Ways to use matchingFieldIdeal:
===============================

  * "matchingFieldIdeal(FlMatchingField)"
  * "matchingFieldIdeal(GrMatchingField)"

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

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

plueckerMap -- The ring map of the Pluecker embedding
*****************************************************

Synopsis
========

  * Usage:
        m = plueckerMap L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a string (Macaulay2Doc), default value
        "default", either "default" or "none" (supply "none" only if $L$ is not
        coherent)
  * Outputs:
      * m, a ring map (Macaulay2Doc), the ring map of the
        Pluecker embedding

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

The ring map for the Pluecker embedding of the Grassmannian sends each Pluecker
variable $P_J$, where $J$ is a $k$-subset of $[n]$, to its corresponding
maximal minor in a generic $k \times n$ matrix of variables $X = (x_{i,j})$.

The domain and codomain of this ring map are naturally equipped with term
orders derived from a weight matrix, which induces the matching field. So, for
this function, we require that the matching fields be coherent. If a weight
matrix is not supplied, then one is automatically computed. If the matching
field is not coherent, then an error is thrown.

+-----------------------------------------------------------------------------+
|i1 : L = grMatchingField(2, 4, {{1, 2}, {1, 3}, {3, 2}, {1, 4}, {4, 2}, {3,  |
|                                                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)                                |
|                                                                             |
|o1 : GrMatchingField                                                         |
|-----------------------------------------------------------------------------|
|4}})                                                                         |
+-----------------------------------------------------------------------------+
|i2 : isCoherent L                                                            |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : getWeightMatrix L                                                       |
|                                                                             |
|o3 = | 0 0  0  0  |                                                          |
|     | 0 -3 -1 -2 |                                                          |
|                                                                             |
|              2       4                                                      |
|o3 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i4 : plueckerMap L                                                           |
|                                                                             |
|o4 = map (QQ[x   ..x   ], QQ[p   ..p   , p   , p   , p   , p   ], {x   x    -|
|              1,1   2,4       1,2   1,3   2,3   1,4   2,4   3,4     1,1 2,2  |
|                                                                             |
|o4 : RingMap QQ[x   ..x   ] <-- QQ[p   ..p   , p   , p   , p   , p   ]       |
|                 1,1   2,4          1,2   1,3   2,3   1,4   2,4   3,4        |
|-----------------------------------------------------------------------------|
|x   x   , x   x    - x   x   , - x   x    + x   x   , x   x    - x   x   , - |
| 1,2 2,1   1,1 2,3    1,3 2,1     1,3 2,2    1,2 2,3   1,1 2,4    1,4 2,1    |
|-----------------------------------------------------------------------------|
|x   x    + x   x   , x   x    - x   x   })                                   |
| 1,4 2,2    1,2 2,4   1,3 2,4    1,4 2,3                                     |
+-----------------------------------------------------------------------------+
|i5 : describe target plueckerMap L                                           |
|                                                                             |
|o5 = QQ[x   ..x   , Degrees => {8:1}, Heft => {1}, MonomialOrder =>          |
|         1,1   2,4                                                           |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32       }]                                                 |
|{Weights => {5:0, 3, 1..2}}                                                  |
|{GRevLex => {8:1}         }                                                  |
|{Position => Up           }                                                  |
+-----------------------------------------------------------------------------+

For the above polynomial ring, the monomial order is given by a weight
ordering. Note that the weights are based on $-1 \times W$ where $W$ is the
weight matrix that induces $L$, displayed using the function
getWeightMatrix. The purpose of $-1$ is to transition between
the minimum convention of matching fields and the maximum convention of initial
terms in Macaulay2 (Macaulay2Doc).

The ring map for the Pluecker embedding of a partial flag variety is completely
analogous.

+-----------------------------------------------------------------------------+
|i6 : L = diagonalMatchingField({1,2}, 4)                                     |
|                                                                             |
|o6 = Flag Matching Field for Fl(1, 2; 4)                                     |
|                                                                             |
|o6 : FlMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i7 : getWeightMatrix L                                                       |
|                                                                             |
|o7 = | 0 0 0 0 |                                                             |
|     | 4 3 2 1 |                                                             |
|                                                                             |
|              2       4                                                      |
|o7 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i8 : m = plueckerMap L                                                       |
|                                                                             |
|o8 = map (QQ[x   ..x   ], QQ[p ..p , p   ..p   , p   , p   , p   ,           |
|              1,1   2,4       1   4   1,2   1,3   2,3   1,4   2,4            |
|                                                                             |
|o8 : RingMap QQ[x   ..x   ] <-- QQ[p ..p , p   ..p   , p   , p   ,           |
|                 1,1   2,4          1   4   1,2   1,3   2,3   1,4            |
|-----------------------------------------------------------------------------|
|p   ], {x   , x   , x   , x   , x   x    - x   x   , x   x    - x   x   ,    |
| 3,4     1,1   1,2   1,3   1,4   1,1 2,2    1,2 2,1   1,1 2,3    1,3 2,1     |
|                                                                             |
|p   , p   ]                                                                  |
| 2,4   3,4                                                                   |
|-----------------------------------------------------------------------------|
|x   x    - x   x   , x   x    - x   x   , x   x    - x   x   , x   x    -    |
| 1,2 2,3    1,3 2,2   1,1 2,4    1,4 2,1   1,2 2,4    1,4 2,2   1,3 2,4      |
|-----------------------------------------------------------------------------|
|x   x   })                                                                   |
| 1,4 2,3                                                                     |
+-----------------------------------------------------------------------------+
|i9 : describe source m                                                       |
|                                                                             |
|o9 = QQ[p ..p , p   ..p   , p   , p   , p   , p   , Degrees => {10:1}, Heft  |
|         1   4   1,2   1,3   2,3   1,4   2,4   3,4                           |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|=> {1}, MonomialOrder => {MonomialSize => 32        }]                       |
|                         {Weights => {5:0, 2:1, 3:2}}                        |
|                         {GRevLex => {10:1}         }                        |
|                         {Position => Up            }                        |
+-----------------------------------------------------------------------------+

The monomial order on the ring of Pluecker variables, shown above, is also
based on $-1 \times W$. More concretely, the weight vector of a Pluecker
variable $P_J$ is the weight of the initial term of the image of the Pluecker
variable $m(P_J) = \det(X_J)$ under the map.

The monomial map associated to the matching field, see
matchingFieldRingMap, is the map that sends each Pluecker
variable $P_J \mapsto \rm{in}(\det(X_J))$ to the lead term of the maximal minor
$\det(X_J)$.

Ways to use plueckerMap:
========================

  * "plueckerMap(FlMatchingField)"
  * "plueckerMap(GrMatchingField)"

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

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

matchingFieldRingMap -- monomial map of the matching field
**********************************************************

Synopsis
========

  * Usage:
        m = matchingFieldRingMap L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a string (Macaulay2Doc), default value
        "default", either "default" or "none" (supply "none" only when $L$ is
        not coherent)
  * Outputs:
      * m, a ring map (Macaulay2Doc), monomial ring map whose
        kernel is the matching field ideal

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

Each tuple $J = (j_1, j_2, \dots, j_k)$ of a matching field defines a monomial
given by $m(J) = c x_{1, j_1} x_{2, j_2} \dots x_{k, j_k}$ where the
coefficient $c \in \{+1, -1\}$ is the sign of the permutation that permutes $J$
into ascending order. Equivalently, $c = (-1)^d$ where $d = |\{(a, b) \in [k]^2
: a < b, j_a > j_b \}|$ is the number of descents of $J$. The monomial $m(J)$
is the lead term of the corresponding Pluecker form with respect to the weight
order given by the matching field.

+-----------------------------------------------------------------------------+
|i1 : L = matchingFieldFromPermutation(2, 4, {2, 3, 4, 1})                    |
|                                                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)                                |
|                                                                             |
|o1 : GrMatchingField                                                         |
+-----------------------------------------------------------------------------+
|i2 : getTuples L                                                             |
|                                                                             |
|o2 = {{2, 1}, {3, 1}, {3, 2}, {1, 4}, {2, 4}, {3, 4}}                        |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : matchingFieldRingMap L                                                  |
|                                                                             |
|o3 = map (QQ[x   ..x   ], QQ[p   ..p   , p   , p   , p   , p   ], {-x   x   ,|
|              1,1   2,4       1,2   1,3   2,3   1,4   2,4   3,4      1,2 2,1 |
|                                                                             |
|o3 : RingMap QQ[x   ..x   ] <-- QQ[p   ..p   , p   , p   , p   , p   ]       |
|                 1,1   2,4          1,2   1,3   2,3   1,4   2,4   3,4        |
|-----------------------------------------------------------------------------|
|-x   x   , -x   x   , x   x   , x   x   , x   x   })                         |
|  1,3 2,1    1,3 2,2   1,1 2,4   1,2 2,4   1,3 2,4                           |
+-----------------------------------------------------------------------------+
|i4 : plueckerForms = matrix plueckerMap L                                    |
|                                                                             |
|o4 = | -x_(1,2)x_(2,1)+x_(1,1)x_(2,2) -x_(1,3)x_(2,1)+x_(1,1)x_(2,3)         |
|     ------------------------------------------------------------------------|
|     -x_(1,3)x_(2,2)+x_(1,2)x_(2,3) x_(1,1)x_(2,4)-x_(1,4)x_(2,1)            |
|     ------------------------------------------------------------------------|
|     x_(1,2)x_(2,4)-x_(1,4)x_(2,2) x_(1,3)x_(2,4)-x_(1,4)x_(2,3) |           |
|                                                                             |
|                            1                     6                          |
|o4 : Matrix (QQ[x   ..x   ])  <-- (QQ[x   ..x   ])                           |
|                 1,1   2,4             1,1   2,4                             |
+-----------------------------------------------------------------------------+
|i5 : leadTerm plueckerForms                                                  |
|                                                                             |
|o5 = | -x_(1,2)x_(2,1) -x_(1,3)x_(2,1) -x_(1,3)x_(2,2) x_(1,1)x_(2,4)        |
|     ------------------------------------------------------------------------|
|     x_(1,2)x_(2,4) x_(1,3)x_(2,4) |                                         |
|                                                                             |
|                            1                     6                          |
|o5 : Matrix (QQ[x   ..x   ])  <-- (QQ[x   ..x   ])                           |
|                 1,1   2,4             1,1   2,4                             |
+-----------------------------------------------------------------------------+
|i6 : leadTerm plueckerForms == matrix matchingFieldRingMap L                 |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Note that the polynomial rings have weight-based term orders that depend on a
weight matrix that induces the matching field. So if the matching field
supplied is not coherent then function gives an error. To check that a matching
field is coherent use the function isCoherent.

See also
========

  * getTuples -- The tuples of a matching field
  * plueckerMap -- The ring map of the Pluecker embedding
  * isCoherent -- Is the matching field coherent

Ways to use matchingFieldRingMap:
=================================

  * "matchingFieldRingMap(FlMatchingField)"
  * "matchingFieldRingMap(GrMatchingField)"

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

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

plueckerAlgebra -- Pluecker algebra of a (partial) flag variety
***************************************************************

Synopsis
========

  * Usage:
        S = plueckerAlgebra L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a string (Macaulay2Doc), default value
        "default", either "default" or "none" (supply "none" only if $L$ is not
        coherent)
  * Outputs:
      * S, an instance of the type Subring (SubalgebraBases),
        generated by minors of a generic matrix of variables

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

The Pluecker algebra for the Grassmannian is generated by the maximal minors of
a generic $k \times n$ matrix of variables. Similarly, for a partial flag
variety, the Pluecker algebra is generated by a collection of top-justified
minors of a generic matrix of variables.

A matching field specifies a weight order on the ambient ring containing the
Pluecker algebra.

+---------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)               |
|                                                   |
|o1 = Grassmannian Matching Field for Gr(2, 4)      |
|                                                   |
|o1 : GrMatchingField                               |
+---------------------------------------------------+
|i2 : S = plueckerAlgebra L                         |
|                                                   |
|o2 = QQ[p_0..p_5], subring of QQ[x_(1,1)..x_(2,4)] |
|                                                   |
|o2 : Subring                                       |
+---------------------------------------------------+
|i3 : transpose gens S                              |
|                                                   |
|o3 = {-2} | x_(1,1)x_(2,2)-x_(1,2)x_(2,1) |        |
|     {-2} | x_(1,1)x_(2,3)-x_(1,3)x_(2,1) |        |
|     {-2} | x_(1,2)x_(2,3)-x_(1,3)x_(2,2) |        |
|     {-2} | x_(1,1)x_(2,4)-x_(1,4)x_(2,1) |        |
|     {-2} | x_(1,2)x_(2,4)-x_(1,4)x_(2,2) |        |
|     {-2} | x_(1,3)x_(2,4)-x_(1,4)x_(2,3) |        |
|                                                   |
|                            6                     1|
|o3 : Matrix (QQ[x   ..x   ])  <-- (QQ[x   ..x   ]) |
|                 1,1   2,4             1,1   2,4   |
+---------------------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * FlMatchingField -- the class of matching fields for
    partial flag varieties
  * plueckerMap -- The ring map of the Pluecker embedding
  * Subring (SubalgebraBases) -- The type of all subrings

Ways to use plueckerAlgebra:
============================

  * "plueckerAlgebra(FlMatchingField)"
  * "plueckerAlgebra(GrMatchingField)"

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

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

matchingFieldPolytope -- The polytope of a matching field
*********************************************************

Synopsis
========

  * Usage:
        P = matchingFieldPolytope L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * ExtraZeroRows => an integer (Macaulay2Doc), default value 0,
        produces a matching field polytope embedded in a larger space typically
        used for producing polytopes of flag matching field
  * Outputs:
      * P, a convex polyhedron (Polyhedra), polytope of the
        matching field

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

Each matching field defines a projective toric variety whose defining ideal is
given by the kernel of the monomial map. See matchingFieldRingMap.
The coordinate ring of this toric variety is the Ehrhart
ring of the matching field polytope. Note that for flag matching fields, the
toric variety is embedded into a high-dimensional projective space via the
Segre embedding whose domain is a product of Grassmannians.

Given a matching field $\Lambda$ for the Grassmannian Gr$(k,n)$, the matching
field polytope $P(\Lambda)$ is simply the convex hull of the exponent vectors
of the image of Pluecker variables under the monomial map of $\Lambda$. The
polytope naturally lives in the space $\RR^{k \times n}$.

+---------------------------------------------+
|i1 : L2 = diagonalMatchingField(2, 4)        |
|                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)|
|                                             |
|o1 : GrMatchingField                         |
+---------------------------------------------+
|i2 : P2 = matchingFieldPolytope L2           |
|                                             |
|o2 = P2                                      |
|                                             |
|o2 : Polyhedron                              |
+---------------------------------------------+
|i3 : fVector P2                              |
|                                             |
|o3 = {6, 13, 13, 6, 1}                       |
|                                             |
|o3 : List                                    |
+---------------------------------------------+
|i4 : vertices P2                             |
|                                             |
|o4 = | 1 1 0 1 0 0 |                         |
|     | 0 0 1 0 1 0 |                         |
|     | 0 0 0 0 0 1 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 1 0 0 0 0 0 |                         |
|     | 0 1 1 0 0 0 |                         |
|     | 0 0 0 1 1 1 |                         |
|                                             |
|              8       6                      |
|o4 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+

The columns of the above matrix are the vertices of the matching field polytope
$P(\Lambda)$. Each column should be thought of as a $2 \times 4$ matrix whose
entries are listed row by row.

A matching field $\Lambda$ for a partial flag variety Fl$(k_1, \dots, k_s; n)$
is a union of matching fields $\Lambda = \bigcup \Lambda_i$ for some
Grassmannians. The matching field polytope for a partial flag variety is the
Minkowski sum $P(\Lambda) = \sum P(\Lambda_i)$ of Grassmannian matching field
polytopes in $\Lambda$. For this sum to make sense, each Grassmannian matching
field polytope must be put into the same space, which is taken to be
$\RR^{k_{\max} \times n}$ where $k_{\max} = \max\{k_i\}$ is the largest $k$
such that there is a Grassmannian matching field for Gr$(k,n)$ contained in
$\Lambda$. If $v \in \RR^{k_i \times n}$ is a vertex for a Grassmannian
matching field polytope, then we embed $v$ into $\RR^{k_{\max} \times n}$ by
joining a suitably sized matrix of zeros to $v$ from below.

Embedding a Grassmannian matching field polytope into a higher dimensional
space as described is done by specifying the optional value
ExtraZeroRows.

+-------------------------------------------------------+
|i5 : L1 = diagonalMatchingField(1, 4)                  |
|                                                       |
|o5 = Grassmannian Matching Field for Gr(1, 4)          |
|                                                       |
|o5 : GrMatchingField                                   |
+-------------------------------------------------------+
|i6 : P1 = matchingFieldPolytope(L1, ExtraZeroRows => 1)|
|                                                       |
|o6 = P1                                                |
|                                                       |
|o6 : Polyhedron                                        |
+-------------------------------------------------------+
|i7 : vertices P1                                       |
|                                                       |
|o7 = | 1 0 0 0 |                                       |
|     | 0 1 0 0 |                                       |
|     | 0 0 1 0 |                                       |
|     | 0 0 0 1 |                                       |
|     | 0 0 0 0 |                                       |
|     | 0 0 0 0 |                                       |
|     | 0 0 0 0 |                                       |
|     | 0 0 0 0 |                                       |
|                                                       |
|              8       4                                |
|o7 : Matrix QQ  <-- QQ                                 |
+-------------------------------------------------------+
|i8 : P12 = minkowskiSum(P1, P2)                        |
|                                                       |
|o8 = P12                                               |
|                                                       |
|o8 : Polyhedron                                        |
+-------------------------------------------------------+
|i9 : vertices P12                                      |
|                                                       |
|o9 = | 2 1 1 1 2 0 1 0 1 0 2 0 0 1 0 0 |               |
|     | 0 1 0 0 0 2 0 1 0 1 0 2 0 0 1 0 |               |
|     | 0 0 1 0 0 0 1 1 0 0 0 0 2 0 0 1 |               |
|     | 0 0 0 1 0 0 0 0 1 1 0 0 0 1 1 1 |               |
|     | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |               |
|     | 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 |               |
|     | 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 |               |
|     | 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 |               |
|                                                       |
|              8       16                               |
|o9 : Matrix QQ  <-- QQ                                 |
+-------------------------------------------------------+

The above example constructs the diagonal matching field polytope for the
partial flag variety Fl$(1, 2; 4)$ as a Minkowski sum. The quick way to do this
is as follows.

+-----------------------------------------+
|i10 : L = diagonalMatchingField({1,2}, 4)|
|                                         |
|o10 = Flag Matching Field for Fl(1, 2; 4)|
|                                         |
|o10 : FlMatchingField                    |
+-----------------------------------------+
|i11 : Q = matchingFieldPolytope L        |
|                                         |
|o11 = Q                                  |
|                                         |
|o11 : Polyhedron                         |
+-----------------------------------------+
|i12 : Q == P12                           |
|                                         |
|o12 = true                               |
+-----------------------------------------+

See also
========

  * ExtraZeroRows -- enlarging a matrix with zero rows

Ways to use matchingFieldPolytope:
==================================

  * "matchingFieldPolytope(FlMatchingField)"
  * "matchingFieldPolytope(GrMatchingField)"

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

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

ExtraZeroRows -- enlarging a matrix with zero rows
**************************************************

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

The option ExtraZeroRows, is used by the functions
matchingFieldPolytope, and weightMatrixCone.
In each case, the option controls the ambient space of the
polyhedron. By default the value is zero. It is typically used internally for
computing Minkowski sums of polyhedra that would ordinarily belong to different
ambient spaces.

+-----------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                 |
|                                                     |
|o1 = Grassmannian Matching Field for Gr(2, 4)        |
|                                                     |
|o1 : GrMatchingField                                 |
+-----------------------------------------------------+
|i2 : P = matchingFieldPolytope(L, ExtraZeroRows => 1)|
|                                                     |
|o2 = P                                               |
|                                                     |
|o2 : Polyhedron                                      |
+-----------------------------------------------------+
|i3 : vertices P                                      |
|                                                     |
|o3 = | 1 1 0 1 0 0 |                                 |
|     | 0 0 1 0 1 0 |                                 |
|     | 0 0 0 0 0 1 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|     | 1 0 0 0 0 0 |                                 |
|     | 0 1 1 0 0 0 |                                 |
|     | 0 0 0 1 1 1 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|     | 0 0 0 0 0 0 |                                 |
|                                                     |
|              12       6                             |
|o3 : Matrix QQ   <-- QQ                              |
+-----------------------------------------------------+
|i4 : C = weightMatrixCone(L, ExtraZeroRows => 1)     |
|                                                     |
|o4 = C                                               |
|                                                     |
|o4 : Cone                                            |
+-----------------------------------------------------+
|i5 : rays C                                          |
|                                                     |
|o5 = | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  -1 |                                    |
|     | 0  -1 -1 |                                    |
|     | -1 -1 -1 |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|     | 0  0  0  |                                    |
|                                                     |
|              12       3                             |
|o5 : Matrix ZZ   <-- ZZ                              |
+-----------------------------------------------------+

In the above examples, the polyhedral object typically live in the space
$\RR^{2 \times 4}$. However, by adding an additional row, the objects live in
$\RR^{3 \times 4} \cong \RR^{12}$. Reading the down the entries of columns
corresponds to reading row-by-row the entries of the corresponding matrix.

See also
========

  * matchingFieldPolytope -- The polytope of a
    matching field
  * weightMatrixCone -- The cone of weight matrices
    that induce the matching field

Functions with optional argument named ExtraZeroRows:
=====================================================

  * "matchingFieldPolytope(...,ExtraZeroRows=>...)" -- see
    matchingFieldPolytope, -- The polytope of a matching
    field
  * "weightMatrixCone(...,ExtraZeroRows=>...)" -- see weightMatrixCone,
    -- The cone of weight matrices that induce the matching
    field

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

The object ExtraZeroRows, is a symbol (Macaulay2Doc).

NOBody -- Newton-Okounkov body of the matching field
****************************************************

Synopsis
========

  * Usage:
        D = NOBody L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Outputs:
      * D, a convex polyhedron (Polyhedra), Newton-Okounkov
        body of the matching field

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

The Pluecker algebra is generated by Pluecker forms given by top-justified
minors of a generic matrix. The Pluecker algebra can be constructed with the
function plueckerAlgebra, of the image of the Pluecker
ring map that can be accessed with the function plueckerMap.
Note that the ambient ring containing the Pluecker algebra has a
weight-based term order that comes from the matching field. We compute a
subalgebra basis (SAGBI basis) using the package SubalgebraBases,
for the Pluecker algebra.

The Newton-Okounkov body of the matching field is constructed from this
subalgebra basis. In the case of Grassmannian matching fields, the NO body is
simply the convex hull of the exponent vectors of the initial terms of the
subalgebra basis. If the matching field gives rise to a toric degeneration (see
the function isToricDegeneration) then the NO body
coincides with the matching field polytope (see matchingFieldPolytope)
because the maximal minors form a subalgebra basis for
the Pluecker algebra.

+---------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)         |
|                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)|
|                                             |
|o1 : GrMatchingField                         |
+---------------------------------------------+
|i2 : P = matchingFieldPolytope L             |
|                                             |
|o2 = P                                       |
|                                             |
|o2 : Polyhedron                              |
+---------------------------------------------+
|i3 : vertices P                              |
|                                             |
|o3 = | 1 1 0 1 0 0 |                         |
|     | 0 0 1 0 1 0 |                         |
|     | 0 0 0 0 0 1 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 1 0 0 0 0 0 |                         |
|     | 0 1 1 0 0 0 |                         |
|     | 0 0 0 1 1 1 |                         |
|                                             |
|              8       6                      |
|o3 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+
|i4 : noBody = NOBody L                       |
|                                             |
|o4 = noBody                                  |
|                                             |
|o4 : Polyhedron                              |
+---------------------------------------------+
|i5 : vertices noBody                         |
|                                             |
|o5 = | 1 1 0 1 0 0 |                         |
|     | 0 0 1 0 1 0 |                         |
|     | 0 0 0 0 0 1 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 0 0 0 0 0 0 |                         |
|     | 1 0 0 0 0 0 |                         |
|     | 0 1 1 0 0 0 |                         |
|     | 0 0 0 1 1 1 |                         |
|                                             |
|              8       6                      |
|o5 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+
|i6 : P == noBody                             |
|                                             |
|o6 = true                                    |
+---------------------------------------------+

In the case of flag matching fields, the NO body is computed in a similar way.
First a subalgebra basis is computed for the Pluecker algebra. However, to
construct the NO body from the subalgebra basis, we need to take into account
the grading on the Pluecker forms. From the geometric perspective, we are
simply using the Segre embedding to view the flag variety as a subvariety of a
suitably large projective space.

+----------------------------------------+
|i7 : L = diagonalMatchingField({1,2}, 4)|
|                                        |
|o7 = Flag Matching Field for Fl(1, 2; 4)|
|                                        |
|o7 : FlMatchingField                    |
+----------------------------------------+
|i8 : noBody = NOBody L                  |
|                                        |
|o8 = noBody                             |
|                                        |
|o8 : Polyhedron                         |
+----------------------------------------+
|i9 : vertices noBody                    |
|                                        |
|o9 = | 2 1 1 1 2 0 1 0 1 0 2 0 0 1 0 0 ||
|     | 0 1 0 0 0 2 0 1 0 1 0 2 0 0 1 0 ||
|     | 0 0 1 0 0 0 1 1 0 0 0 0 2 0 0 1 ||
|     | 0 0 0 1 0 0 0 0 1 1 0 0 0 1 1 1 ||
|     | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 ||
|                                        |
|              8       16                |
|o9 : Matrix QQ  <-- QQ                  |
+----------------------------------------+
|i10 : noBody == matchingFieldPolytope L |
|                                        |
|o10 = true                              |
+----------------------------------------+

Note that the matching field polytope is equal to the NO body if and only if
the matching field gives rise to a toric degeneration. So, for a hexagonal
matching field for Gr$(3,6)$, the NO body has an additional vertex. We
construct a hexagonal matching field using the function
matchingFieldFromPermutation, as follows.

+-----------------------------------------------------------------------------+
|i11 : L = matchingFieldFromPermutation(3, 6, {6,1,5,2,3,4}, UsePrimePowers =>|
|                                                                             |
|o11 = Grassmannian Matching Field for Gr(3, 6)                               |
|                                                                             |
|o11 : GrMatchingField                                                        |
|-----------------------------------------------------------------------------|
|true, ScalingCoefficient => 3)                                               |
+-----------------------------------------------------------------------------+
|i12 : isToricDegeneration L                                                  |
|                                                                             |
|o12 = false                                                                  |
+-----------------------------------------------------------------------------+
|i13 : vertices NOBody L                                                      |
|                                                                             |
|o13 = | 1 1 1 0 1 0 0 1 1 0 1 0 0 0 1 1 0 0 1 0 1/2 |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 1 0 1 0 0 0 1 0 1 0 0 0 0 1 0 0 1 0   |                        |
|      | 0 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 1 0 0 1/2 |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 1 0 1 1 1 1 1 0 0 0 1 1 1 1 0 0 0 0 0 0 1/2 |                        |
|      | 0 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 1/2 |                        |
|      | 0 1 0 0 0 0 0 0 1 1 0 0 0 0 0 1 1 1 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1/2 |                        |
|      | 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0   |                        |
|      | 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1/2 |                        |
|                                                                             |
|               18       21                                                   |
|o13 : Matrix QQ   <-- QQ                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * matchingFieldFromPermutation, --
    matching field parametrised by permutations
  * isToricDegeneration -- Does the matching field
    give rise to a toric degeneration
  * SubalgebraBases -- A package for finding
    canonical subalgebra bases (SAGBI bases)
  * plueckerAlgebra -- Pluecker algebra of a (partial)
    flag variety
  * plueckerMap -- The ring map of the Pluecker embedding

Ways to use NOBody:
===================

  * "NOBody(FlMatchingField)"
  * "NOBody(GrMatchingField)"

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

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

weightMatrixCone -- The cone of weight matrices that induce the matching field
******************************************************************************

Synopsis
========

  * Usage:
        C = weightMatrixCone L
  * Inputs:
      * L, an instance of the type GrMatchingField, or
        an instance of the type FlMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * ExtraZeroRows => an integer (Macaulay2Doc), default value 0,
        produces a cone embedded in a higher dimensional space typically used
        for constructing weight matrix cones for flag matching fields
  * Outputs:
      * C, a convex rational cone (Polyhedra), the cone of weight
        matrices that induce the matching field

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

Given a coherent matching field $\Lambda$, either for the Grassmannian or
partial flag variety, the set of weight matrices that induce $\Lambda$
naturally form a polyhedral cone. The function weightMatrixCone,
constructs this cone by writing down a collection of
inequalities. To illustrate this assume that $(1,2)$ is a tuple of $\Lambda$. A
weight matrix $M = (m_{i,j})$ induces a matching field with the tuple $(1,2)$
if and only if $m_{1,1} + m_{2,2} < m_{1,2} + m_{2,1}$. Continuing in this way
for all other tuples of $\Lambda$ produces the cone of weight matrices. Note,
the inequalities, like the one above, are strict. So, in general, only the
interior points of the cone give rise to generic weight matrices that induce
the matching field.

+---------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)         |
|                                             |
|o1 = Grassmannian Matching Field for Gr(2, 4)|
|                                             |
|o1 : GrMatchingField                         |
+---------------------------------------------+
|i2 : C = weightMatrixCone L                  |
|                                             |
|o2 = C                                       |
|                                             |
|o2 : Cone                                    |
+---------------------------------------------+
|i3 : rays C                                  |
|                                             |
|o3 = | 0  0  0  |                            |
|     | 0  0  0  |                            |
|     | 0  0  0  |                            |
|     | 0  0  0  |                            |
|     | 0  0  0  |                            |
|     | 0  0  -1 |                            |
|     | 0  -1 -1 |                            |
|     | -1 -1 -1 |                            |
|                                             |
|              8       3                      |
|o3 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
|i4 : linealitySpace C                        |
|                                             |
|o4 = | 1 1 0 0 -1 |                          |
|     | 1 0 1 0 -1 |                          |
|     | 1 0 0 1 -1 |                          |
|     | 1 0 0 0 0  |                          |
|     | 0 1 0 0 0  |                          |
|     | 0 0 1 0 0  |                          |
|     | 0 0 0 1 0  |                          |
|     | 0 0 0 0 1  |                          |
|                                             |
|              8       5                      |
|o4 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
|i5 : dim C                                   |
|                                             |
|o5 = 8                                       |
+---------------------------------------------+

In the above example, we can see that adding a vector from the lineality space
can be interpreted as adding a constant to each element in a specific row or
column of the weight matrix.

For matching fields that are not originally defined by a weight matrix, the
cone of weight matrices allows us to test if the matching field is coherent.
The matching field is coherent if and only if the cone is full dimensional.
This is the strategy implemented by the function isCoherent.

+--------------------------------------------------------+
|i6 : L = grMatchingField(2, 3, {{1, 2}, {2, 3}, {3, 1}})|
|                                                        |
|o6 = Grassmannian Matching Field for Gr(2, 3)           |
|                                                        |
|o6 : GrMatchingField                                    |
+--------------------------------------------------------+
|i7 : isCoherent L                                       |
|                                                        |
|o7 = false                                              |
+--------------------------------------------------------+
|i8 : dim weightMatrixCone L                             |
|                                                        |
|o8 = 4                                                  |
+--------------------------------------------------------+

In the example above, the cone naturally lives in $\RR^6$ so it is not full
dimensional. Therefore, the matching field is not coherent.

Ways to use weightMatrixCone:
=============================

  * "weightMatrixCone(FlMatchingField)"
  * "weightMatrixCone(GrMatchingField)"

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

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

algebraicMatroid -- The algebraic matroid of the tropical cone that induces the matroid
***************************************************************************************

Synopsis
========

  * Usage:
        M = algebraicMatroid L
  * Inputs:
      * L, an instance of the type GrMatchingField,
  * Outputs:
      * M, matroid, The algebraic matroid of the cone in Trop Gr$(k,n)$ that
        induces the matching field.

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

Let $V \subseteq \CC^n$ be an affine variety. The algebraic matroid of $V$ is a
matroid whose independent sets $S \subseteq [n]$ are the subsets such that the
projection from $V$ to the coordinates indexed by $S$ is a dominant morphism.
Similarly, if $C \subseteq \RR^n$ is a polyhedral cone, then the algebraic
matroid of $C$ is the matroid whose independent sets $S \subseteq [n]$ are the
subsets such that image of the projection of $C$ onto the coordinates indexed
by $S$ is full-dimensional.

In the case of the affine cone of Grassmannian under the Pluecker embedding,
there are a few different ways to compute its algebraic matroid. One way is to
use its tropicalization. The algebraic matroid of the Grassmannian is equal to
the matroid whose bases are the union of all bases of the algebraic matroid for
all maximal cones of Trop Gr($k$, $n$).

For each coherent matching field, we compute its cone in the tropicalization of
the Grassmannian. We compute the algebraic matroid of this cone. To view the
bases of this matroid in terms of the $k$-subsets of $[n]$, use the function
algebraicMatroidBases. Similarly, to view its
circuits use algebraicMatroidCircuits,

+--------------------------------------------------------------------------+
|i1 : L = grMatchingField(2, 4, {{1,2}, {1,3}, {1,4}, {2,3}, {2,4}, {3,4}})|
|                                                                          |
|o1 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o1 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i2 : M = algebraicMatroid L                                               |
|                                                                          |
|o2 = a "matroid" of rank 5 on 6 elements                                  |
|                                                                          |
|o2 : Matroid                                                              |
+--------------------------------------------------------------------------+
|i3 : netList algebraicMatroidBases L                                      |
|                                                                          |
|     +--------------------------------------------+                       |
|o3 = |set {{1, 2}, {1, 3}, {1, 4}, {2, 3}, {3, 4}}|                       |
|     +--------------------------------------------+                       |
|     |set {{1, 2}, {1, 3}, {2, 3}, {2, 4}, {3, 4}}|                       |
|     +--------------------------------------------+                       |
|     |set {{1, 2}, {1, 3}, {1, 4}, {2, 4}, {3, 4}}|                       |
|     +--------------------------------------------+                       |
|     |set {{1, 2}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}|                       |
|     +--------------------------------------------+                       |
+--------------------------------------------------------------------------+

See also
========

  * algebraicMatroidBases -- The bases of the
    algebraic matroid
  * algebraicMatroidCircuits -- The bases of
    the algebraic matroid

Ways to use algebraicMatroid:
=============================

  * "algebraicMatroid(GrMatchingField)"

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

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

algebraicMatroidCircuits -- The bases of the algebraic matroid
**************************************************************

Synopsis
========

  * Usage:
        C = algebraicMatroidCircuits L
  * Inputs:
      * L, an instance of the type GrMatchingField,
  * Outputs:
      * C, a list (Macaulay2Doc), the circuits of the algebraic
        matroid of the matching field as $k$-subsets

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

Displays the circuits of the algebraic matroid associated to the Grassmannian
Gr$(k,n)$ matching field in terms of the $k$-subsets of $[n]$. For more details
about the matroid, see the function algebraicMatroid.

+-----------------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 5)                       |
|                                                           |
|o1 = Grassmannian Matching Field for Gr(2, 5)              |
|                                                           |
|o1 : GrMatchingField                                       |
+-----------------------------------------------------------+
|i2 : netList algebraicMatroidCircuits L                    |
|                                                           |
|     +----------------------------------------------------+|
|o2 = |set {{1, 3}, {2, 3}, {1, 4}, {2, 4}}                ||
|     +----------------------------------------------------+|
|     |set {{1, 3}, {2, 3}, {1, 5}, {2, 5}}                ||
|     +----------------------------------------------------+|
|     |set {{1, 4}, {2, 4}, {1, 5}, {2, 5}}                ||
|     +----------------------------------------------------+|
|     |set {{3, 5}, {1, 4}, {1, 5}, {3, 4}}                ||
|     +----------------------------------------------------+|
|     |set {{3, 5}, {1, 3}, {2, 3}, {1, 5}, {2, 4}, {3, 4}}||
|     +----------------------------------------------------+|
|     |set {{3, 5}, {1, 3}, {1, 4}, {2, 3}, {2, 5}, {3, 4}}||
|     +----------------------------------------------------+|
|     |set {{3, 5}, {2, 4}, {2, 5}, {3, 4}}                ||
|     +----------------------------------------------------+|
+-----------------------------------------------------------+

See also
========

  * algebraicMatroid -- The algebraic matroid of the
    tropical cone that induces the matroid
  * algebraicMatroidCircuits -- The bases of
    the algebraic matroid

Ways to use algebraicMatroidCircuits:
=====================================

  * "algebraicMatroidCircuits(GrMatchingField)"

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

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

algebraicMatroidBases -- The bases of the algebraic matroid
***********************************************************

Synopsis
========

  * Usage:
        B = algebraicMatroidBases L
  * Inputs:
      * L, an instance of the type GrMatchingField,
  * Outputs:
      * B, a list (Macaulay2Doc), the bases of the algebraic
        matroid of the matching field as $k$-subsets

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

Displays the bases of the algebraic matroid associated to the Grassmannian
Gr$(k,n)$ matching field in terms of the $k$-subsets of $[n]$. For more details
about the matroid, see the function algebraicMatroid.

+---------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)               |
|                                                   |
|o1 = Grassmannian Matching Field for Gr(2, 4)      |
|                                                   |
|o1 : GrMatchingField                               |
+---------------------------------------------------+
|i2 : netList algebraicMatroidBases L               |
|                                                   |
|     +--------------------------------------------+|
|o2 = |set {{1, 2}, {1, 3}, {1, 4}, {2, 3}, {3, 4}}||
|     +--------------------------------------------+|
|     |set {{1, 2}, {1, 3}, {2, 3}, {2, 4}, {3, 4}}||
|     +--------------------------------------------+|
|     |set {{1, 2}, {1, 3}, {1, 4}, {2, 4}, {3, 4}}||
|     +--------------------------------------------+|
|     |set {{1, 2}, {2, 3}, {1, 4}, {2, 4}, {3, 4}}||
|     +--------------------------------------------+|
+---------------------------------------------------+

See also
========

  * algebraicMatroid -- The algebraic matroid of the
    tropical cone that induces the matroid
  * algebraicMatroidCircuits -- The bases of
    the algebraic matroid

Ways to use algebraicMatroidBases:
==================================

  * "algebraicMatroidBases(GrMatchingField)"

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

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

matroidSubdivision -- The matroid subdivision induced by the Pluecker weight of a coherent matching field
*********************************************************************************************************

Synopsis
========

  * Usage:
        listOfBases = matroidSubdivision L
        listOfBases = matroidSubdivision(k, n, plueckerWeight)
  * Inputs:
      * L, an instance of the type GrMatchingField,
      * k, an integer (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
      * plueckerWeight, a list (Macaulay2Doc), the weight of the
        pluecker coordinates in revLex order using minimum convention
  * Outputs:
      * listOfBases, a list (Macaulay2Doc), Each element is a list
        of the vertices of a maximal cell of the matroid subdivision of the
        hypersimplex induced by the Pluecker weight of the matching field.

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

The hypersimplex $\Delta(k, n) \subseteq \RR^{n}$ is the convex hull of the
characteristic vectors of all $k$-subsets of $\{1, \dots, n\}$, and we label
each vertex with with its corresponding subset. A regular subdivision of the
vertices of $\Delta(k, n)$ is said to be matroidal if, for each maximal cell of
the subdivision, the subsets labelling its vertices form the set of bases of a
matroid. The well-known result is: a point lies in the Dressian Dr($k$, $n$),
the tropical prevariety of all $3$-term Pluecker relation in Gr($k$, $n$), if
and only if it induces a matroidal subdivision of the hypersimplex.

+--------------------------------------------------------------------------+
|i1 : L = grMatchingField(2, 4, {{1,2}, {1,3}, {1,4}, {2,3}, {2,4}, {3,4}})|
|                                                                          |
|o1 = Grassmannian Matching Field for Gr(2, 4)                             |
|                                                                          |
|o1 : GrMatchingField                                                      |
+--------------------------------------------------------------------------+
|i2 : netList matroidSubdivision L -- an octahedron sliced into 2 pieces   |
|                                                                          |
|     +------+------+------+------+------+                                 |
|o2 = |{1, 4}|{2, 4}|{1, 3}|{2, 3}|{1, 2}|                                 |
|     +------+------+------+------+------+                                 |
|     |{1, 4}|{2, 4}|{3, 4}|{1, 3}|{2, 3}|                                 |
|     +------+------+------+------+------+                                 |
+--------------------------------------------------------------------------+

Whenever the function matroidSubdivision, is supplied
with a Grassmannian matching field, the cached weight that induces the matching
field is used for the computation of the matroid subdivision. Note that, if the
function is supplied directly with the \textit{plueckerWeight}, then the
coordinates are ordered so that the corresponding sets are listed in reverse
lexicographic order.

Ways to use matroidSubdivision:
===============================

  * "matroidSubdivision(GrMatchingField)"
  * "matroidSubdivision(ZZ,ZZ,List)"

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

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

linearSpanTropCone -- linear span of the tropical cone associated to the matching field
***************************************************************************************

Synopsis
========

  * Usage:
        linSpace = linearSpanTropCone L
  * Inputs:
      * L, an instance of the type GrMatchingField,
  * Optional inputs (Macaulay2Doc),:
      * VerifyToricDegeneration => a Boolean value (Macaulay2Doc),
        default value true, controls if
        isToricDegeneration, is run
  * Outputs:
      * linSpace, a module (Macaulay2Doc), a free QQ-module, the
        linear span of the cone in the tropicalisation corresponding to the
        matching field

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

Suppose that $I$ is an ideal and $in_w(I)$ is a binomial initial ideal of $I$
with resepct to a weight $w$. Let $C_w$ be the cone in the Groebner fan of $I$
that contains $w$ in its relative interior. The linear span of $C_w$ can be
constructed from a generating set of $in_w(I)$. Each generator $x^u - x^v$
gives a hyperplane defined by kernel of $(0 .. 0, 1_u, 0 .. 0, -1_v, 0 .. 0)$.
The intersection of these hyperplanes gives the linear span of the Groebner
cone.

The function linearSpanTropCone, checks if the
supplied matching field gives rise to a toric degeneration, which happens if
and only if the initial ideal of the Pluecker ideal is toric, i.e., the ideal
is generated by binomials and is prime. If it is already known that the
matching field gives rise to a toric degeneration then set the option
VerifyToricDegeneration, to false to avoid repeating this
check.

The linear span is a realisation of the algebraic matroid associated to the
matching field. See the function algebraicMatroid.

+----------------------------------------------------------------------+
|i1 : L = diagonalMatchingField(2, 4)                                  |
|                                                                      |
|o1 = Grassmannian Matching Field for Gr(2, 4)                         |
|                                                                      |
|o1 : GrMatchingField                                                  |
+----------------------------------------------------------------------+
|i2 : linearSpanTropCone L                                             |
|                                                                      |
|o2 = image | 1 0 0 0  0 |                                             |
|           | 0 1 1 -1 0 |                                             |
|           | 0 1 0 0  0 |                                             |
|           | 0 0 1 0  0 |                                             |
|           | 0 0 0 1  0 |                                             |
|           | 0 0 0 0  1 |                                             |
|                                                                      |
|                               6                                      |
|o2 : QQ-module, submodule of QQ                                       |
+----------------------------------------------------------------------+
|i3 : algebraicMatroid L == matroid transpose gens linearSpanTropCone L|
|                                                                      |
|o3 = true                                                             |
+----------------------------------------------------------------------+

See also
========

  * algebraicMatroid -- The algebraic matroid of the
    tropical cone that induces the matroid
  * isToricDegeneration -- Does the matching field
    give rise to a toric degeneration

Ways to use linearSpanTropCone:
===============================

  * "linearSpanTropCone(GrMatchingField)"

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

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

TopeField -- A tope field structure on a matching field
*******************************************************

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

Tope fields were introduced in the study of tropical oriented matroids and have
been used generalise and study matching fields. In this package we follow the
conventions of tope fields given by Smith and Loho, i.e., the type of a tope
field contains positive entries.

The combinatorial data of a tope field is given by a matching field for
$Gr(k,n)$ together with a type: $(t_1, \dots, t_s)$ where $t_1 + \dots + t_s =
k$ and each $t_i$ is a positive integer. The bipartite graphs of the tope field
are encoded in the tuples of the matching field as follows. Let $(i_{1,1},
i_{1,2}, \dots i_{1,t_1}, i_{2,1}, \dots, i_{s, t_s})$ be a tuple of the
matching field, the bipartite graph on vertices $L := [n]$ and $R := [s]$ has
edges $\{i_{j, t}, j\}$ where $j \in [s]$ and $t \in [t_j]$.

For example, if $(1,3,2)$ is a tuple of a matching field for $Gr(3,4)$ of a
tope field of type $(2,1)$, then corresponding bipartite graph on vertices $L =
[4]$ and $R = [2]$ has edges: $E = \{11, 31, 22 \}$.

The TopeField type in this package is a HashTable that stores the matching
field and type. A tope field can be defined from a matching field using the
constructor topeField. New tope fields can be constructed
from old using the function amalgamation. Note that
amalgamation is only defined for linkage tope field, see isLinkage.

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * topeField -- Constructor of a tope field
  * amalgamation -- The $i$th amalgamation of a tope field
  * isLinkage -- Test if a tope field is linkage

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

  * "amalgamation(ZZ,TopeField)" -- see amalgamation, --
    The $i$th amalgamation of a tope field
  * getTuples(TopeField) -- tuples of a tope
    field
  * "isLinkage(TopeField)" -- see isLinkage, -- Test if a tope
    field is linkage
  * net(TopeField) -- display a tope field

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

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

topeField -- Constructor of a tope field
****************************************

Synopsis
========

  * Usage:
        TF = topeField MF
        TF = topeField(MF, T)
  * Inputs:
      * MF, an instance of the type GrMatchingField,
        matching field containing the tuples of the tope field
      * T, a list (Macaulay2Doc), the type of the tope field
  * Outputs:
      * TF, an instance of the type TopeField,

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

The standard constructor of a tope field. If the constructor is supplied with a
matching field and no type, then the type is automatically set to $1,1, \dots,
1$.

+-------------------------------------------+
|i1 : MF = diagonalMatchingField(3,6);      |
+-------------------------------------------+
|i2 : TF = topeField MF                     |
|                                           |
|o2 = Tope field: n = 6 and type = {1, 1, 1}|
|                                           |
|o2 : TopeField                             |
+-------------------------------------------+
|i3 : TF' = topeField(MF, {2,1})            |
|                                           |
|o3 = Tope field: n = 6 and type = {2, 1}   |
|                                           |
|o3 : TopeField                             |
+-------------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * TopeField -- A tope field structure on a matching field
  * amalgamation -- The $i$th amalgamation of a tope field

Ways to use topeField:
======================

  * "topeField(GrMatchingField)"
  * "topeField(GrMatchingField,List)"

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

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

net(TopeField) -- display a tope field
**************************************

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net TF
  * Inputs:
      * TF, an instance of the type TopeField,
  * Outputs:
      * a net (Macaulay2Doc),

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

The net (Macaulay2Doc), of a tope field displays $n$ and the type of
the tope field. See TopeField.

See also
========

  * TopeField -- A tope field structure on a matching field

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

  * net(TopeField) -- display a tope field

getTuples(TopeField) -- tuples of a tope field
**********************************************

Synopsis
========

  * Function: getTuples,
  * Usage:
        tuples = getTuples TF
  * Inputs:
      * TF, an instance of the type TopeField,
  * Outputs:
      * tuples, a list (Macaulay2Doc), list of tuples of the
        matching field of the tope field

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

Lists the tuples of the matching field of the tope field.

+-----------------------------------------------------------------------------+
|i1 : L = diagonalMatchingField(3, 6);                                        |
+-----------------------------------------------------------------------------+
|i2 : T = topeField L                                                         |
|                                                                             |
|o2 = Tope field: n = 6 and type = {1, 1, 1}                                  |
|                                                                             |
|o2 : TopeField                                                               |
+-----------------------------------------------------------------------------+
|i3 : getTuples T                                                             |
|                                                                             |
|o3 = {{1, 2, 3}, {1, 2, 4}, {1, 3, 4}, {2, 3, 4}, {1, 2, 5}, {1, 3, 5}, {2,  |
|     ------------------------------------------------------------------------|
|     3, 5}, {1, 4, 5}, {2, 4, 5}, {3, 4, 5}, {1, 2, 6}, {1, 3, 6}, {2, 3, 6},|
|     ------------------------------------------------------------------------|
|     {1, 4, 6}, {2, 4, 6}, {3, 4, 6}, {1, 5, 6}, {2, 5, 6}, {3, 5, 6}, {4, 5,|
|     ------------------------------------------------------------------------|
|     6}}                                                                     |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * TopeField -- A tope field structure on a matching field

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

  * getTuples(TopeField) -- tuples of a tope
    field

isLinkage -- Test if a tope field is linkage
********************************************

Synopsis
========

  * Usage:
        result = isLinkage MF
        result = isLinkage TF
  * Inputs:
      * MF, an instance of the type GrMatchingField,
      * TF, an instance of the type TopeField,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc),

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

Consider a tope field given by a collection of bipartite graphs. The tope field
is said to be linkage if for each $k+1$-subset $S$ of $[n]$, the union of the
edges of the bipartite graphs $G$ where the non-isolated left-vertices of $G$
are contained in $S$, is a forest.

Note that all coherent matching fields are linkage.

+------------------------------------+
|i1 : L = diagonalMatchingField(2,4);|
+------------------------------------+
|i2 : isLinkage L                    |
|                                    |
|o2 = true                           |
+------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * TopeField -- A tope field structure on a matching field
  * amalgamation -- The $i$th amalgamation of a tope field

Ways to use isLinkage:
======================

  * "isLinkage(GrMatchingField)"
  * "isLinkage(TopeField)"

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

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

amalgamation -- The $i$th amalgamation of a tope field
******************************************************

Synopsis
========

  * Usage:
        result = amalgamation(i, MF)
        result = amalgamation(i, TF)
  * Inputs:
      * i, an integer (Macaulay2Doc), the $i$th amalgamation
      * MF, an instance of the type GrMatchingField,
      * TF, an instance of the type TopeField,
  * Outputs:
      * result, an instance of the type TopeField,

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

Computes the $i$th amalgamation of a tope field. Note that the tope field must
be linkage for amalgamation to be well-defined.

+-----------------------------------------------------------------------------+
|i1 : L = matchingFieldFromPermutation(3,6,{4,5,6,1,2,3});                    |
+-----------------------------------------------------------------------------+
|i2 : getTuples L                                                             |
|                                                                             |
|o2 = {{2, 1, 3}, {2, 1, 4}, {3, 1, 4}, {3, 2, 4}, {2, 1, 5}, {3, 1, 5}, {3,  |
|     ------------------------------------------------------------------------|
|     2, 5}, {1, 4, 5}, {2, 4, 5}, {3, 4, 5}, {2, 1, 6}, {3, 1, 6}, {3, 2, 6},|
|     ------------------------------------------------------------------------|
|     {1, 4, 6}, {2, 4, 6}, {3, 4, 6}, {1, 5, 6}, {2, 5, 6}, {3, 5, 6}, {5, 4,|
|     ------------------------------------------------------------------------|
|     6}}                                                                     |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : T = topeField L                                                         |
|                                                                             |
|o3 = Tope field: n = 6 and type = {1, 1, 1}                                  |
|                                                                             |
|o3 : TopeField                                                               |
+-----------------------------------------------------------------------------+
|i4 : T1 = amalgamation(1, T)                                                 |
|                                                                             |
|o4 = Tope field: n = 6 and type = {2, 1, 1}                                  |
|                                                                             |
|o4 : TopeField                                                               |
+-----------------------------------------------------------------------------+
|i5 : getTuples T1                                                            |
|                                                                             |
|o5 = {{2, 3, 1, 4}, {2, 3, 1, 5}, {1, 2, 4, 5}, {1, 3, 4, 5}, {2, 3, 4, 5},  |
|     ------------------------------------------------------------------------|
|     {2, 3, 1, 6}, {1, 2, 4, 6}, {1, 3, 4, 6}, {2, 3, 4, 6}, {1, 2, 5, 6},   |
|     ------------------------------------------------------------------------|
|     {1, 3, 5, 6}, {2, 3, 5, 6}, {1, 5, 4, 6}, {2, 5, 4, 6}, {3, 5, 4, 6}}   |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * GrMatchingField -- the class of Grassmannian
    matching fields
  * grMatchingField -- Construct a matching field for
    the Grassmannian variety
  * TopeField -- A tope field structure on a matching field
  * topeField -- Constructor of a tope field
  * isLinkage -- Test if a tope field is linkage

Ways to use amalgamation:
=========================

  * "amalgamation(ZZ,GrMatchingField)"
  * "amalgamation(ZZ,TopeField)"

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

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