This is SparseResultants.info, produced by Macaulay2, version 1.20

SparseResultants -- computations with sparse resultants
*******************************************************

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

This package provides the methods sparseResultant, and
sparseDiscriminant, to calculate sparse resultants
and sparse discriminants. As an application, the method
determinant(MultidimensionalMatrix),
is also provided. See also the package Resultants,
which includes methods to calculate dense resultants and dense discriminants.

For the definitions, see one of the following books:

(1) Discriminants, Resultants, and Multidimensional Determinants (see
http://link.springer.com/book/10.1007%2F978-0-8176-4771-1 ), by Israel M.
Gelfand, Mikhail M. Kapranov and Andrei V. Zelevinsky;

(2) Using Algebraic Geometry (see
http://link.springer.com/book/10.1007%2Fb138611 ), by David A. Cox, John
Little, Donal O'shea.

Caveat
======

Currently, most of the algorithms implemented are based on elimination via
Gröbner basis methods. This should be significantly improved by implementing
more specialized algorithms (see e.g. [2 (see
http://link.springer.com/book/10.1007%2Fb138611 ), Chapter 7,Section 6]).

Author
======

  * Giovanni Staglianò <giovannistagliano@gmail.com>

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

Version 1.1 of this package was accepted for publication in volume 11 (see
https://msp.org/jsag/2021/11-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 5 May 2021, in the article A package for
computations with sparse resultants (see
https://msp.org/jsag/2021/11-1/p07.xhtml ). That version can be obtained from
the journal (see https://msp.org/jsag/2021/11-1/jsag-v11-n1-x07-
SparseResultants.m2 ) or from the Macaulay2 source code repository (see
http://github.com/Macaulay2/M2/blob/4b0b826f08857b22cf17aebf9c56257ff44d8946/M2
/Macaulay2/packages/SparseResultants.m2 ).

Version
=======

This documentation describes version 1.2 of SparseResultants.

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

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

Exports
=======

  * Types
      * MultidimensionalMatrix -- the class of
        all multidimensional matrices
      * SparseDiscriminant -- the class of all
        sparse discriminants
      * SparseResultant -- the class of all sparse
        resultants
  * Functions and commands
      * degreeDeterminant -- degree of the
        hyperdeterminant of a generic multidimensional matrix
      * denseDiscriminant -- dense discriminant
        (classical discriminant)
      * denseResultant -- dense resultant (classical
        resultant)
      * exponentsMatrix -- exponents in one or more
        polynomials
      * flattening -- flattening of a multidimensional
        matrix
      * genericLaurentPolynomials -- generic
        (Laurent) polynomials
      * genericMultidimensionalMatrix, --
        make a generic multidimensional matrix of variables
      * genericMultihomogeneousPolynomial
        -- generic multi-homogeneous
        polynomial
      * genericSkewMultidimensionalMatrix
        -- make a generic skew symmetric
        multidimensional matrix of variables
      * genericSymmetricMultidimensionalMatrix
        -- make a generic symmetric
        multidimensional matrix of variables
      * multidimensionalMatrix -- make a
        multidimensional matrix
      * permute -- permute the dimensions of a multidimensional
        matrix
      * randomMultidimensionalMatrix, --
        random multidimensional matrix
      * reverseShape -- reverse the dimensions of a
        multidimensional matrix
      * shape -- shape of a multidimensional matrix
      * sortShape -- sort the dimensions of a
        multidimensional matrix
      * sparseDiscriminant -- sparse discriminant
        (A-discriminant)
      * sparseResultant -- sparse resultant
        (A-resultant)
      * sylvesterMatrix -- Sylvester-type matrix for
        the hyperdeterminant of a matrix of boundary shape
  * Methods
      * char(SparseDiscriminant) -- get
        the characteristic
      * char(SparseResultant) -- get the
        characteristic
      * "degreeDeterminant(List)" -- see degreeDeterminant,
        -- degree of the hyperdeterminant of a generic
        multidimensional matrix
      * "denseDiscriminant(RingElement)" -- see denseDiscriminant,
        -- dense discriminant (classical discriminant)
      * "denseDiscriminant(ZZ,ZZ)" -- see denseDiscriminant,
        -- dense discriminant (classical discriminant)
      * "denseResultant(Thing)" -- see denseResultant, --
        dense resultant (classical resultant)
      * determinant(MultidimensionalMatrix)
        -- hyperdeterminant of a
        multidimensional matrix
      * dim(MultidimensionalMatrix), --
        dimension of a multidimensional matrix
      * entries(MultidimensionalMatrix)
        -- lists the entries of a
        multidimensional matrix
      * exponents(SparseDiscriminant),
        -- get the matrix of exponents
      * exponents(SparseResultant), --
        get the matrices of exponents
      * "exponentsMatrix(Sequence)" -- see exponentsMatrix,
        -- exponents in one or more polynomials
      * "flattening(List,MultidimensionalMatrix)" -- see flattening,
        -- flattening of a multidimensional matrix
      * "flattening(ZZ,MultidimensionalMatrix)" -- see flattening,
        -- flattening of a multidimensional matrix
      * "genericLaurentPolynomials(Sequence)" -- see
        genericLaurentPolynomials, -- generic
        (Laurent) polynomials
      * "genericMultidimensionalMatrix(VisibleList)" -- see
        genericMultidimensionalMatrix, -- make a
        generic multidimensional matrix of variables
      * "genericMultihomogeneousPolynomial(VisibleList,VisibleList)" -- see
        genericMultihomogeneousPolynomial,
        -- generic multi-homogeneous
        polynomial
      * "genericSkewMultidimensionalMatrix(ZZ,ZZ)" -- see
        genericSkewMultidimensionalMatrix,
        -- make a generic skew symmetric multidimensional matrix of variables
      * "genericSymmetricMultidimensionalMatrix(ZZ,ZZ)" -- see
        genericSymmetricMultidimensionalMatrix,
        -- make a generic symmetric
        multidimensional matrix of variables
      * "multidimensionalMatrix(List)" -- see multidimensionalMatrix,
        -- make a multidimensional matrix
      * MultidimensionalMatrix * MultidimensionalMatrix
        -- product of
        multidimensional matrices
      * MultidimensionalMatrix + MultidimensionalMatrix
        -- sum of two
        multidimensional matrices of the same shape
      * MultidimensionalMatrix - MultidimensionalMatrix
        -- difference of two
        multidimensional matrices of the same shape
      * MultidimensionalMatrix == MultidimensionalMatrix
        -- equality of two
        multidimensional matrices
      * MultidimensionalMatrix _ Sequence
        -- get entry of multidimensional matrix
      * multidimensionalMatrix(RingElement)
        -- make a multidimensional
        matrix from a multilinear form
      * "permute(MultidimensionalMatrix,List)" -- see permute,
        -- permute the dimensions of a multidimensional matrix
      * "randomMultidimensionalMatrix(VisibleList)" -- see
        randomMultidimensionalMatrix, -- random
        multidimensional matrix
      * rank(MultidimensionalMatrix),
        -- about the border rank of a multidimensional matrix
      * "reverseShape(MultidimensionalMatrix)" -- see reverseShape,
        -- reverse the dimensions of a multidimensional matrix
      * ring(MultidimensionalMatrix),
        -- ring of a multidimensional matrix
      * RingElement * MultidimensionalMatrix
        -- product of a scalar with a multidimensional
        matrix
      * "shape(MultidimensionalMatrix)" -- see shape, -- shape of
        a multidimensional matrix
      * "sortShape(MultidimensionalMatrix)" -- see sortShape,
        -- sort the dimensions of a multidimensional matrix
      * "sparseDiscriminant(Matrix)" -- see sparseDiscriminant,
        -- sparse discriminant (A-discriminant)
      * "sparseDiscriminant(RingElement)" -- see sparseDiscriminant,
        -- sparse discriminant (A-discriminant)
      * SparseDiscriminant Thing -- evaluate a
        sparse discriminant
      * "sparseResultant(Thing)" -- see sparseResultant,
        -- sparse resultant (A-resultant)
      * SparseResultant Thing -- evaluate a
        sparse resultant

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

The object SparseResultants, is a package (Macaulay2Doc).

char(SparseDiscriminant) -- get the characteristic
**************************************************

Synopsis
========

  * Function: char (Macaulay2Doc),
  * Usage:
        char D
  * Inputs:
      * D, an instance of the type SparseDiscriminant,
  * Outputs:
      * an integer (Macaulay2Doc), the characteristic of the ring of
        the polynomial representing D

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

+-----------------------------------------------------------------------------+
|i1 : D = denseDiscriminant(2,2,CoefficientRing=>ZZ/331);                     |
|                                                                             |
|o1 : SparseDiscriminant (sparse discriminant associated to | 0 0 0 1 1 2 |   |
|                                                           | 0 1 2 0 1 0 |   |
|-----------------------------------------------------------------------------|
|over ZZ/331)                                                                 |
+-----------------------------------------------------------------------------+
|i2 : char D                                                                  |
|                                                                             |
|o2 = 331                                                                     |
+-----------------------------------------------------------------------------+
|i3 : char denseDiscriminant(2,2)                                             |
|                                                                             |
|o3 = 0                                                                       |
+-----------------------------------------------------------------------------+

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

  * char(SparseDiscriminant) -- get the
    characteristic

char(SparseResultant) -- get the characteristic
***********************************************

Synopsis
========

  * Function: char (Macaulay2Doc),
  * Usage:
        char R
  * Inputs:
      * R, an instance of the type SparseResultant,
  * Outputs:
      * an integer (Macaulay2Doc), the characteristic of the ring of
        the polynomial representing R

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

+-----------------------------------------------------------------------------+
|i1 : R = denseResultant(2,2,1,CoefficientRing=>ZZ/331);                      |
|                                                                             |
|o1 : SparseResultant (sparse mixed resultant associated to {| 0 0 0 1 1 2 |, |
|                                                            | 0 1 2 0 1 0 |  |
|-----------------------------------------------------------------------------|
|| 0 0 0 1 1 2 |, | 0 0 1 |} over ZZ/331)                                     |
|| 0 1 2 0 1 0 |  | 0 1 0 |                                                   |
+-----------------------------------------------------------------------------+
|i2 : char R                                                                  |
|                                                                             |
|o2 = 331                                                                     |
+-----------------------------------------------------------------------------+
|i3 : char denseResultant(2,2,1)                                              |
|                                                                             |
|o3 = 0                                                                       |
+-----------------------------------------------------------------------------+

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

  * char(SparseResultant) -- get the
    characteristic

degreeDeterminant -- degree of the hyperdeterminant of a generic multidimensional matrix
****************************************************************************************

Synopsis
========

  * Usage:
        degreeDeterminant n
  * Inputs:
      * n, a list (Macaulay2Doc), a list of positive integers
        $n=\{n_1,n_2,\ldots\}$
  * Outputs:
      * an integer (Macaulay2Doc), the degree of the hyperdeterminant
        of a generic multidimensional matrix of shape $n_1\times
        n_2\times\ldots$

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

+--------------------------------------------------------------------+
|i1 : n = {2,3,2}                                                    |
|                                                                    |
|o1 = {2, 3, 2}                                                      |
|                                                                    |
|o1 : List                                                           |
+--------------------------------------------------------------------+
|i2 : time degreeDeterminant n                                       |
|     -- used 0.000102534 seconds                                    |
|                                                                    |
|o2 = 6                                                              |
+--------------------------------------------------------------------+
|i3 : M = genericMultidimensionalMatrix n;                           |
|                                                                    |
|o3 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ[a     ..a     ]|
|                                                      0,0,0   1,2,1 |
+--------------------------------------------------------------------+
|i4 : time degree determinant M                                      |
|     -- used 0.245082 seconds                                       |
|                                                                    |
|o4 = {6}                                                            |
|                                                                    |
|o4 : List                                                           |
+--------------------------------------------------------------------+

See also
========

  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix
  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables

Ways to use degreeDeterminant :
===============================

  * "degreeDeterminant(List)"

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

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

denseDiscriminant -- dense discriminant (classical discriminant)
****************************************************************

Synopsis
========

  * Usage:
        denseDiscriminant(d,n)
        denseDiscriminant f
  * Inputs:
      * (d,n), a pair of two integers representing, respectively, the degree
        and the number of variables of a Laurent polynomial $f$.
      * f, a ring element (Macaulay2Doc), a Laurent
        polynomial of degree $d$ in $n$ variables.
  * Optional inputs (Macaulay2Doc),:
      * Algorithm => ..., default value "Poisson"
      * CoefficientRing => ..., default value ZZ
  * Outputs:
      * for (d,n), this is the same as sparseDiscriminant,
        see exponentsMatrix, "generic
        polynomial of degree d in n variables";
      * for f, this is the same as affineDiscriminant (Resultants),
        (f).

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

+-----------------------------------------------------------------------------+
|i1 : (d,n) := (2,3);                                                         |
+-----------------------------------------------------------------------------+
|i2 : time Disc = denseDiscriminant(d,n)                                      |
|     -- used 0.380669 seconds                                                |
|                                                                             |
|o2 = Disc                                                                    |
|                                                                             |
|o2 : SparseDiscriminant (sparse discriminant associated to | 0 0 0 0 0 0 1 1 |
|                                                           | 0 0 0 1 1 2 0 0 |
|                                                           | 0 1 2 0 1 0 0 1 |
|-----------------------------------------------------------------------------|
|1 2 |)                                                                       |
|1 0 |                                                                        |
|0 0 |                                                                        |
+-----------------------------------------------------------------------------+
|i3 : f = first genericLaurentPolynomials prepend(d,n:0)                      |
|                                                                             |
|        2               2                        2                           |
|o3 = a x  + a x x  + a x  + a x x  + a x x  + a x  + a x  + a x  + a x  + a  |
|      9 1    8 1 2    5 2    7 1 3    4 2 3    2 3    6 1    3 2    1 3    0 |
|                                                                             |
|o3 : ZZ[a ..a , b , c , d ][x ..x ]                                          |
|         0   9   0   0   0   1   3                                           |
+-----------------------------------------------------------------------------+
|i4 : assert(Disc(f) == denseDiscriminant(f))                                 |
+-----------------------------------------------------------------------------+

See also
========

  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)
  * affineDiscriminant (Resultants) -- affine
    discriminant
  * denseResultant -- dense resultant (classical
    resultant)
  * exponentsMatrix -- exponents in one or more
    polynomials
  * genericLaurentPolynomials -- generic
    (Laurent) polynomials

Ways to use denseDiscriminant :
===============================

  * "denseDiscriminant(RingElement)"
  * "denseDiscriminant(ZZ,ZZ)"

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

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

denseResultant -- dense resultant (classical resultant)
*******************************************************

Synopsis
========

  * Usage:
        denseResultant(d_0,d_1,...)
        denseResultant(f_0,f_1,...)
  * Inputs:
      * (d_0,d_1,...), a sequence of integers.
      * (f_0,f_1,...), a sequence of $n+1$ Laurent polynomials in $n$
        variables.
  * Optional inputs (Macaulay2Doc),:
      * Algorithm => ..., default value "Poisson"
      * CoefficientRing => ..., default value ZZ
  * Outputs:
      * for (d_0,d_1,...), this is the same as sparseResultant,
        see exponentsMatrix,
        genericLaurentPolynomials,(d_0,d_1,...);
      * for (f_0,f_1,...), this is the same as affineResultant (Resultants),
        {f_0,f_1,...}.

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

+-----------------------------------------------------------------------------+
|i1 : (f0,f1,f2) = genericLaurentPolynomials(1,2,2)                           |
|                                                                             |
|                           2               2                        2        |
|o1 = (a x  + a x  + a , b x  + b x x  + b x  + b x  + b x  + b , c x  +      |
|       2 1    1 2    0   5 1    4 1 2    2 2    3 1    1 2    0   5 1        |
|     ------------------------------------------------------------------------|
|                 2                                                           |
|     c x x  + c x  + c x  + c x  + c )                                       |
|      4 1 2    2 2    3 1    1 2    0                                        |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : time denseResultant(f0,f1,f2); -- using Poisson formula                 |
|     -- used 0.310819 seconds                                                |
+-----------------------------------------------------------------------------+
|i3 : time denseResultant(f0,f1,f2,Algorithm=>"Macaulay"); -- using Macaulay  |
|     -- used 1.32136 seconds                                                 |
|-----------------------------------------------------------------------------|
|formula                                                                      |
+-----------------------------------------------------------------------------+
|i4 : time (denseResultant(1,2,2)) (f0,f1,f2); -- using sparseResultant       |
|     -- used 0.980764 seconds                                                |
+-----------------------------------------------------------------------------+
|i5 : assert(o2 == o3 and o3 == o4)                                           |
+-----------------------------------------------------------------------------+

See also
========

  * sparseResultant -- sparse resultant (A-resultant)
  * affineResultant (Resultants) -- affine resultant
  * denseDiscriminant -- dense discriminant
    (classical discriminant)
  * exponentsMatrix -- exponents in one or more
    polynomials
  * genericLaurentPolynomials -- generic
    (Laurent) polynomials

Ways to use denseResultant :
============================

  * "denseResultant(Thing)"

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

The object denseResultant, is a method function with a single argument (Macaulay2Doc).

determinant(MultidimensionalMatrix) -- hyperdeterminant of a multidimensional matrix
************************************************************************************

Synopsis
========

  * Function: determinant (Macaulay2Doc),
  * Usage:
        det M
  * Inputs:
      * M, a multidimensional matrix,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (Macaulay2Doc),
        => ..., default value null, null
  * Outputs:
      * a ring element (Macaulay2Doc), the hyperdeterminant
        of $M$

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

This is calculated using Schlafli's method where it is known to work. Use an
optional input as Strategy=>"forceSchlafliMethod" to try to force this approach
(but without ensuring the correctness of the calculation). For matrices of
boundary shape, the calculation passes through sylvesterMatrix.
For details, see the Chapter 14 in the book Discriminants,
Resultants, and Multidimensional Determinants (see
http://link.springer.com/book/10.1007%2F978-0-8176-4771-1 ).

+-----------------------------------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix(2,2,2,2)                               |
|                                                                             |
|o1 = {{{{8, 1}, {3, 7}}, {{8, 3}, {3, 7}}}, {{{8, 8}, {5, 7}}, {{8, 5}, {2,  |
|     ------------------------------------------------------------------------|
|     3}}}}                                                                   |
|                                                                             |
|o1 : 4-dimensional matrix of shape 2 x 2 x 2 x 2 over ZZ                     |
+-----------------------------------------------------------------------------+
|i2 : time det M                                                              |
|     -- used 0.0992061 seconds                                               |
|                                                                             |
|o2 = 9698337990421512192                                                     |
+-----------------------------------------------------------------------------+
|i3 : M = randomMultidimensionalMatrix(2,2,2,2,5)                             |
|                                                                             |
|o3 = {{{{{6, 3, 6, 8, 6}, {9, 3, 7, 6, 9}}, {{6, 2, 6, 0, 2}, {6, 9, 3, 5,   |
|     ------------------------------------------------------------------------|
|     6}}}, {{{3, 5, 7, 7, 9}, {4, 5, 0, 4, 3}}, {{1, 8, 9, 1, 2}, {9, 6, 6,  |
|     ------------------------------------------------------------------------|
|     2, 6}}}}, {{{{4, 0, 9, 8, 3}, {7, 9, 0, 5, 1}}, {{8, 2, 2, 1, 7}, {5, 6,|
|     ------------------------------------------------------------------------|
|     7, 4, 5}}}, {{{4, 0, 1, 4, 4}, {2, 6, 1, 1, 4}}, {{5, 4, 9, 7, 4}, {6,  |
|     ------------------------------------------------------------------------|
|     4, 8, 4, 2}}}}}                                                         |
|                                                                             |
|o3 : 5-dimensional matrix of shape 2 x 2 x 2 x 2 x 5 over ZZ                 |
+-----------------------------------------------------------------------------+
|i4 : time det M                                                              |
|     -- used 0.703456 seconds                                                |
|                                                                             |
|o4 = 912984499996938980479447727885644530753184525786986940737407301278806287|
|     9257139493926586400187927813888                                         |
+-----------------------------------------------------------------------------+

See also
========

  * MultidimensionalMatrix -- the class of all
    multidimensional matrices
  * degreeDeterminant -- degree of the
    hyperdeterminant of a generic multidimensional matrix
  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)
  * sylvesterMatrix -- Sylvester-type matrix for the
    hyperdeterminant of a matrix of boundary shape

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

  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix

dim(MultidimensionalMatrix) -- dimension of a multidimensional matrix
*********************************************************************

Synopsis
========

  * Function: dim (Macaulay2Doc),
  * Usage:
        dim M
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix of shape $k_1\times\cdots\times k_n$
  * Outputs:
      * an integer (Macaulay2Doc), the integer $n$

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{0, 8, 3}, {7, 3, 2}, {2, 7, 0}, {4, 8, 4}}|
|                                                                             |
|o1 = {{{0, 8, 3}, {7, 3, 2}, {2, 7, 0}, {4, 8, 4}}, {{0, 8, 1}, {3, 1, 0},   |
|     ------------------------------------------------------------------------|
|     {4, 7, 4}, {0, 6, 9}}}                                                  |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 4 x 3 over ZZ                         |
|-----------------------------------------------------------------------------|
|, {{0, 8, 1}, {3, 1, 0}, {4, 7, 4}, {0, 6, 9}}}                              |
+-----------------------------------------------------------------------------+
|i2 : dim M                                                                   |
|                                                                             |
|o2 = 3                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * shape(MultidimensionalMatrix) -- shape of a multidimensional
    matrix

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

  * dim(MultidimensionalMatrix), --
    dimension of a multidimensional matrix

entries(MultidimensionalMatrix) -- lists the entries of a multidimensional matrix
*********************************************************************************

Synopsis
========

  * Function: entries (Macaulay2Doc),
  * Usage:
        entries M
  * Inputs:
      * M, a multidimensional matrix,
  * Outputs:
      * a list (Macaulay2Doc), the hyperrectangular nested list of
        the entries of M

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

+-----------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix {3,3}          |
|                                                     |
|o1 = {{8, 1, 3}, {7, 8, 3}, {3, 7, 8}}               |
|                                                     |
|o1 : 2-dimensional matrix of shape 3 x 3 over ZZ     |
+-----------------------------------------------------+
|i2 : entries M                                       |
|                                                     |
|o2 = {{8, 1, 3}, {7, 8, 3}, {3, 7, 8}}               |
|                                                     |
|o2 : List                                            |
+-----------------------------------------------------+
|i3 : M = randomMultidimensionalMatrix {2,2,3}        |
|                                                     |
|o3 = {{{8, 5, 7}, {8, 5, 2}}, {{3, 6, 3}, {6, 8, 6}}}|
|                                                     |
|o3 : 3-dimensional matrix of shape 2 x 2 x 3 over ZZ |
+-----------------------------------------------------+
|i4 : entries M                                       |
|                                                     |
|o4 = {{{8, 5, 7}, {8, 5, 2}}, {{3, 6, 3}, {6, 8, 6}}}|
|                                                     |
|o4 : List                                            |
+-----------------------------------------------------+

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

  * entries(MultidimensionalMatrix),
    -- lists the entries of a multidimensional matrix

exponents(SparseDiscriminant) -- get the matrix of exponents
************************************************************

Synopsis
========

  * Function: exponents (Macaulay2Doc),
  * Usage:
        exponents D
  * Inputs:
      * D, an instance of the type SparseDiscriminant,
  * Outputs:
      * the matrix of exponents from which the sparse discriminant D is created

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

+---------------------------------------------------------------------------+
|i1 : D = denseDiscriminant(2,2);                                           |
|                                                                           |
|o1 : SparseDiscriminant (sparse discriminant associated to | 0 0 0 1 1 2 |)|
|                                                           | 0 1 2 0 1 0 | |
+---------------------------------------------------------------------------+
|i2 : M = exponents D                                                       |
|                                                                           |
|o2 = | 0 0 0 1 1 2 |                                                       |
|     | 0 1 2 0 1 0 |                                                       |
|                                                                           |
|              2        6                                                   |
|o2 : Matrix ZZ  <--- ZZ                                                    |
+---------------------------------------------------------------------------+
|i3 : assert(D === sparseDiscriminant M)                                    |
+---------------------------------------------------------------------------+

See also
========

  * exponentsMatrix -- exponents in one or more
    polynomials

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

  * exponents(SparseDiscriminant), --
    get the matrix of exponents

exponents(SparseResultant) -- get the matrices of exponents
***********************************************************

Synopsis
========

  * Function: exponents (Macaulay2Doc),
  * Usage:
        exponents R
  * Inputs:
      * R, an instance of the type SparseResultant,
  * Outputs:
      * the matrices of exponents from which the sparse resultant R is created

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

+-----------------------------------------------------------------------------+
|i1 : R = denseResultant(2,2,1);                                              |
|                                                                             |
|o1 : SparseResultant (sparse mixed resultant associated to {| 0 0 0 1 1 2 |, |
|                                                            | 0 1 2 0 1 0 |  |
|-----------------------------------------------------------------------------|
|| 0 0 0 1 1 2 |, | 0 0 1 |})                                                 |
|| 0 1 2 0 1 0 |  | 0 1 0 |                                                   |
+-----------------------------------------------------------------------------+
|i2 : M = exponents R                                                         |
|                                                                             |
|o2 = {| 0 0 0 1 1 2 |, | 0 0 0 1 1 2 |, | 0 0 1 |}                           |
|      | 0 1 2 0 1 0 |  | 0 1 2 0 1 0 |  | 0 1 0 |                            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : assert(R === sparseResultant M)                                         |
+-----------------------------------------------------------------------------+

See also
========

  * exponentsMatrix -- exponents in one or more
    polynomials

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

  * exponents(SparseResultant) -- get
    the matrices of exponents

exponentsMatrix -- exponents in one or more polynomials
*******************************************************

Synopsis
========

  * Usage:
        exponentsMatrix(f_0,f_1,...)
  * Inputs:
      * (f_0,f_1,...) one or more Laurent polynomials in the same ring.
  * Optional inputs (Macaulay2Doc),:
      * Unmixed => ..., default value null
  * Outputs:
      * (A_0,A_1,...) a sequence of matrices such that the columns of A_i are
        the exponents (Macaulay2Doc), of f_i. If either the
        option Unmixed is set to true or all the matrices A_i are equal, then
        just one matrix is returned whose columns are all the exponents
        occurring in at least one of the polynomials.

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

+------------------------------------------------------------+
|i1 : QQ[x,y,z];                                             |
+------------------------------------------------------------+
|i2 : f = (x^2 - 7 + x*y*z^11 + y, -3*y^7*z + x^3*y + 5*x^2);|
+------------------------------------------------------------+
|i3 : exponentsMatrix(f_0)                                   |
|                                                            |
|o3 = | 0 0 1  2 |                                           |
|     | 0 1 1  0 |                                           |
|     | 0 0 11 0 |                                           |
|                                                            |
|              3        4                                    |
|o3 : Matrix ZZ  <--- ZZ                                     |
+------------------------------------------------------------+
|i4 : exponentsMatrix(f_0,f_1)                               |
|                                                            |
|o4 = (| 0 0 1  2 |, | 0 2 3 |)                              |
|      | 0 1 1  0 |  | 7 0 1 |                               |
|      | 0 0 11 0 |  | 1 0 0 |                               |
|                                                            |
|o4 : Sequence                                               |
+------------------------------------------------------------+
|i5 : exponentsMatrix(f_0,f_1,Unmixed=>true)                 |
|                                                            |
|o5 = | 0 0 0 1  2 3 |                                       |
|     | 0 1 7 1  0 1 |                                       |
|     | 0 0 1 11 0 0 |                                       |
|                                                            |
|              3        6                                    |
|o5 : Matrix ZZ  <--- ZZ                                     |
+------------------------------------------------------------+

See also
========

  * exponents (Macaulay2Doc) -- the exponents of a polynomial
  * sparseResultant -- sparse resultant (A-resultant)
  * genericLaurentPolynomials -- generic
    (Laurent) polynomials

Ways to use exponentsMatrix :
=============================

  * "exponentsMatrix(Sequence)"

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

The object exponentsMatrix, is a method function with a single argument (Macaulay2Doc).

flattening -- flattening of a multidimensional matrix
*****************************************************

Synopsis
========

  * Usage:
        flattening(s,M)
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix
      * s, a list (Macaulay2Doc), a subset of {0,1,...,n-1}
  * Outputs:
      * a matrix (Macaulay2Doc), the flattening of M
        corresponding to the partition (s,{0,1,...,n-1} - s)

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

+-----------------------------------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix(2,4,3,2)                               |
|                                                                             |
|o1 = {{{{8, 1}, {3, 7}, {8, 3}}, {{3, 7}, {8, 8}, {5, 7}}, {{8, 5}, {2, 3},  |
|     ------------------------------------------------------------------------|
|     {6, 3}}, {{6, 8}, {6, 9}, {3, 7}}}, {{{6, 9}, {6, 2}, {6, 0}}, {{2, 6}, |
|     ------------------------------------------------------------------------|
|     {9, 3}, {5, 6}}, {{3, 5}, {7, 7}, {9, 4}}, {{5, 0}, {4, 3}, {1, 8}}}}   |
|                                                                             |
|o1 : 4-dimensional matrix of shape 2 x 4 x 3 x 2 over ZZ                     |
+-----------------------------------------------------------------------------+
|i2 : s = {0,2};                                                              |
+-----------------------------------------------------------------------------+
|i3 : Ms = flattening(s,M)                                                    |
|                                                                             |
|o3 = | 8 1 3 7 8 5 6 8 |                                                     |
|     | 3 7 8 8 2 3 6 9 |                                                     |
|     | 8 3 5 7 6 3 3 7 |                                                     |
|     | 6 9 2 6 3 5 5 0 |                                                     |
|     | 6 2 9 3 7 7 4 3 |                                                     |
|     | 6 0 5 6 9 4 1 8 |                                                     |
|                                                                             |
|              6        8                                                     |
|o3 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i4 : s' = {1,3};                                                             |
+-----------------------------------------------------------------------------+
|i5 : Ms' = flattening(s',M)                                                  |
|                                                                             |
|o5 = | 8 3 8 6 6 6 |                                                         |
|     | 1 7 3 9 2 0 |                                                         |
|     | 3 8 5 2 9 5 |                                                         |
|     | 7 8 7 6 3 6 |                                                         |
|     | 8 2 6 3 7 9 |                                                         |
|     | 5 3 3 5 7 4 |                                                         |
|     | 6 6 3 5 4 1 |                                                         |
|     | 8 9 7 0 3 8 |                                                         |
|                                                                             |
|              8        6                                                     |
|o5 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i6 : assert(Ms == transpose Ms')                                             |
+-----------------------------------------------------------------------------+

If the first argument is an integer i, it is interpreted as the list {i}.

+------------------------------------+
|i7 : flattening(1,M)                |
|                                    |
|o7 = | 8 1 3 7 8 3 6 9 6 2 6 0 |    |
|     | 3 7 8 8 5 7 2 6 9 3 5 6 |    |
|     | 8 5 2 3 6 3 3 5 7 7 9 4 |    |
|     | 6 8 6 9 3 7 5 0 4 3 1 8 |    |
|                                    |
|              4        12           |
|o7 : Matrix ZZ  <--- ZZ             |
+------------------------------------+
|i8 : assert(oo == flattening({1},M))|
+------------------------------------+

See also
========

  * rank(MultidimensionalMatrix), --
    about the border rank of a multidimensional matrix

Ways to use flattening :
========================

  * "flattening(List,MultidimensionalMatrix)"
  * "flattening(ZZ,MultidimensionalMatrix)"

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

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

genericLaurentPolynomials -- generic (Laurent) polynomials
**********************************************************

Synopsis
========

  * Usage:
        genericLaurentPolynomials A
  * Inputs:
      * A, a sequence (Macaulay2Doc), or a list (Macaulay2Doc),
        of $n+1$ matrices $A_0,\ldots,A_n$ over
        $\mathbb{Z}$ and with $n$ rows to represent the exponent vectors of
        (Laurent) polynomials $f_0,\ldots,f_n$ in $n$ variables. For the dense
        case, one can pass just the sequence of degrees of $f_0,\ldots,f_n$.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
  * Outputs:
      * the generic (Laurent) polynomials $f_0,\ldots,f_n$ in the ring
        $\mathbb{Z}[a_0,a_1,\ldots,b_0,b_1,\ldots][x_1,\ldots,x_n]$, involving
        only the monomials from $A$. (Note that, if all the exponents are
        nonnegative, then the ambient polynomial ring is taken without inverses
        of variables, so that $f_0,\ldots,f_n$ are ordinary polynomials.)

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

This method helps to construct special types of sparse resultants, see for
instance denseResultant.

+-----------------------------------------------------------------------------+
|i1 : M = (matrix{{2,3,4,5},{0,2,1,0}},matrix{{1,-1,0,2,3},{-2,0,-7,-1,0}},   |
|                                                                             |
|o1 = (| 2 3 4 5 |, | 1  -1 0  2  3 |, | -1 0 6 |)                            |
|      | 0 2 1 0 |  | -2 0  -7 -1 0 |  | -2 1 3 |                             |
|                                                                             |
|o1 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|matrix{{-1,0,6},{-2,1,3}})                                                   |
+-----------------------------------------------------------------------------+
|i2 : genericLaurentPolynomials M                                             |
|                                                                             |
|         5      4        3 2      2     3      2 -1        -2      -7        |
|o2 = (a x  + a x x  + a x x  + a x , b x  + b x x   + b x x   + b x   +      |
|       3 1    2 1 2    1 1 2    0 1   4 1    3 1 2     2 1 2     1 2         |
|     ------------------------------------------------------------------------|
|        -1     6 3             -1 -2                                         |
|     b x  , c x x  + c x  + c x  x  )                                        |
|      0 1    2 1 2    1 2    0 1  2                                          |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : genericLaurentPolynomials (2,3,1)                                       |
|                                                                             |
|         2               2                        3      2          2      3 |
|o3 = (a x  + a x x  + a x  + a x  + a x  + a , b x  + b x x  + b x x  + b x  |
|       5 1    4 1 2    2 2    3 1    1 2    0   9 1    8 1 2    6 1 2    3 2 |
|     ------------------------------------------------------------------------|
|          2               2                                                  |
|     + b x  + b x x  + b x  + b x  + b x  + b , c x  + c x  + c )            |
|        7 1    5 1 2    2 2    4 1    1 2    0   2 1    1 2    0             |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * sparseResultant -- sparse resultant (A-resultant)
  * exponentsMatrix -- exponents in one or more
    polynomials

Ways to use genericLaurentPolynomials :
=======================================

  * "genericLaurentPolynomials(Sequence)"

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

The object genericLaurentPolynomials, is a
method function with a single argument (Macaulay2Doc).

genericMultidimensionalMatrix -- make a generic multidimensional matrix of variables
************************************************************************************

Synopsis
========

  * Usage:
        genericMultidimensionalMatrix(d_1,...,d_n)
  * Inputs:
      * (d_1,...,d_n), a sequence of positive integers.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
      * Variable => ..., default value "a"
  * Outputs:
      * the generic multidimensional matrix, of
        shape $d_1\times\cdots\times d_n$.

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

+-----------------------------------------------------------------------------+
|i1 : genericMultidimensionalMatrix(2,4,3)                                    |
|                                                                             |
|o1 = {{{a     , a     , a     }, {a     , a     , a     }, {a     , a     ,  |
|         0,0,0   0,0,1   0,0,2     0,1,0   0,1,1   0,1,2     0,2,0   0,2,1   |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     , a     }}, {{a     , a     , a     }, {a     , |
|      0,2,2     0,3,0   0,3,1   0,3,2       1,0,0   1,0,1   1,0,2     1,1,0  |
|     ------------------------------------------------------------------------|
|     a     , a     }, {a     , a     , a     }, {a     , a     , a     }}}   |
|      1,1,1   1,1,2     1,2,0   1,2,1   1,2,2     1,3,0   1,3,1   1,3,2      |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 4 x 3 over ZZ[a     ..a     ]         |
|                                                      0,0,0   1,3,2          |
+-----------------------------------------------------------------------------+
|i2 : genericMultidimensionalMatrix((2,2,3),CoefficientRing=>ZZ/101)          |
|                                                                             |
|o2 = {{{a     , a     , a     }, {a     , a     , a     }}, {{a     , a     ,|
|         0,0,0   0,0,1   0,0,2     0,1,0   0,1,1   0,1,2       1,0,0   1,0,1 |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     , a     }}}                                     |
|      1,0,2     1,1,0   1,1,1   1,1,2                                        |
|                                                                             |
|                                                   ZZ                        |
|o2 : 3-dimensional matrix of shape 2 x 2 x 3 over ---[a     ..a     ]        |
|                                                  101  0,0,0   1,1,2         |
+-----------------------------------------------------------------------------+
|i3 : genericMultidimensionalMatrix((2,1,3),CoefficientRing=>ZZ/101,Variable  |
|                                                                             |
|o3 = {{{b     , b     , b     }}, {{b     , b     , b     }}}                |
|         0,0,0   0,0,1   0,0,2       1,0,0   1,0,1   1,0,2                   |
|                                                                             |
|                                                   ZZ                        |
|o3 : 3-dimensional matrix of shape 2 x 1 x 3 over ---[b     ..b     ]        |
|                                                  101  0,0,0   1,0,2         |
|-----------------------------------------------------------------------------|
|=>"b")                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * randomMultidimensionalMatrix -- random
    multidimensional matrix
  * genericSymmetricMultidimensionalMatrix
    -- make a generic symmetric
    multidimensional matrix of variables
  * genericSkewMultidimensionalMatrix,
    -- make a generic skew symmetric multidimensional matrix of variables

Ways to use genericMultidimensionalMatrix :
===========================================

  * "genericMultidimensionalMatrix(VisibleList)"

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

The object genericMultidimensionalMatrix,
is a method function with a single argument (Macaulay2Doc).

genericMultihomogeneousPolynomial -- generic multi-homogeneous polynomial
*************************************************************************

Synopsis
========

  * Usage:
        genericMultihomogeneousPolynomial((k_1,...,k_n),(d_1,...,d_n))
  * Inputs:
      * (k_1,...,k_n), a sequence of positive integers to indicate $n$ sets of
        variables $X_1,\ldots,X_n$ with $\#(X_i) = k_i$.
      * (d_1,...,d_n), a sequence of nonnegative integers.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
      * Variable => ..., default value "a"
  * Outputs:
      * a ring element (Macaulay2Doc), the generic
        multi-homogeneous polynomial of multi-degree $(d_1,\ldots,d_n)$ in the
        above sets of variables.

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

This method helps to construct special types of sparse discriminants. For
instance, the hyperdeterminant of a generic $(k_1\times\cdots\times
k_n)$-matrix can be obtained with the code: sparseDiscriminant
genericMultihomogeneousPolynomial((k_1,...,k_n),(1,...,1)).

+-----------------------------------------------------------------------------+
|i1 : genericMultihomogeneousPolynomial((2,2,3),(1,1,1))                      |
|                                                                             |
|o1 = a     x y z  + a     x y z  + a     x y z  + a     x y z  + a     x y z |
|      0,0,0 0 0 0    0,0,1 0 0 1    0,0,2 0 0 2    0,1,0 0 1 0    0,1,1 0 1 1|
|     ------------------------------------------------------------------------|
|     + a     x y z  + a     x y z  + a     x y z  + a     x y z  +           |
|        0,1,2 0 1 2    1,0,0 1 0 0    1,0,1 1 0 1    1,0,2 1 0 2             |
|     ------------------------------------------------------------------------|
|     a     x y z  + a     x y z  + a     x y z                               |
|      1,1,0 1 1 0    1,1,1 1 1 1    1,1,2 1 1 2                              |
|                                                                             |
|o1 : ZZ[a     ..a     ][x ..y , z ..z ]                                      |
|         0,0,0   1,1,2   0   1   0   2                                       |
+-----------------------------------------------------------------------------+
|i2 : genericMultihomogeneousPolynomial((2,3),(3,1))                          |
|                                                                             |
|          3          3          3          2            2            2       |
|o2 = a   x y  + a   x y  + a   x y  + a   x x y  + a   x x y  + a   x x y  + |
|      0,0 0 0    0,1 0 1    0,2 0 2    1,0 0 1 0    1,1 0 1 1    1,2 0 1 2   |
|     ------------------------------------------------------------------------|
|            2            2            2          3          3          3     |
|     a   x x y  + a   x x y  + a   x x y  + a   x y  + a   x y  + a   x y    |
|      2,0 0 1 0    2,1 0 1 1    2,2 0 1 2    3,0 1 0    3,1 1 1    3,2 1 2   |
|                                                                             |
|o2 : ZZ[a   ..a   ][x ..x , y ..y ]                                          |
|         0,0   3,2   0   1   0   2                                           |
+-----------------------------------------------------------------------------+
|i3 : genericMultihomogeneousPolynomial((2,2),(1,1),CoefficientRing=>ZZ/33331)|
|                                                                             |
|o3 = a   x y  + a   x y  + a   x y  + a   x y                                |
|      0,0 0 0    0,1 0 1    1,0 1 0    1,1 1 1                               |
|                                                                             |
|       ZZ                                                                    |
|o3 : -----[a   ..a   ][x ..y ]                                               |
|     33331  0,0   1,1   0   1                                                |
+-----------------------------------------------------------------------------+

See also
========

  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)
  * exponentsMatrix -- exponents in one or more
    polynomials

Ways to use genericMultihomogeneousPolynomial :
===============================================

  * "genericMultihomogeneousPolynomial(VisibleList,VisibleList)"

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

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

genericSkewMultidimensionalMatrix -- make a generic skew symmetric multidimensional matrix of variables
*******************************************************************************************************

Synopsis
========

  * Usage:
        genericSkewMultidimensionalMatrix(n,d)
  * Inputs:
      * (n,d), two positive integers.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value QQ
      * Variable => ..., default value "a"
  * Outputs:
      * the generic skew symmetric multidimensional matrix,
        of shape $d\times\cdots\times d$ ($n$ times).

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

An $n$-dimensional matrix $M$ is skew symmetric if for every permutation $s$ of
the set $\{0,\ldots,n-1\}$ we have permute,(M,s) == sign(s)*M.

+-----------------------------------------------------------------------------+
|i1 : genericSkewMultidimensionalMatrix(3,4)                                  |
|                                                                             |
|o1 = {{{0, 0, 0, 0}, {0, 0, -a , -a }, {0, a , 0, -a }, {0, a , a , 0}}, {{0,|
|                              1    0        1       2        0   2           |
|     ------------------------------------------------------------------------|
|     0, a , a }, {0, 0, 0, 0}, {-a , 0, 0, -a }, {-a , 0, a , 0}}, {{0, -a , |
|         1   0                    1          3      0      3              1  |
|     ------------------------------------------------------------------------|
|     0, a }, {a , 0, 0, a }, {0, 0, 0, 0}, {-a , -a , 0, 0}}, {{0, -a , -a , |
|         2     1         3                    2    3                 0    2  |
|     ------------------------------------------------------------------------|
|     0}, {a , 0, -a , 0}, {a , a , 0, 0}, {0, 0, 0, 0}}}                     |
|           0       3        2   3                                            |
|                                                                             |
|o1 : 3-dimensional matrix of shape 4 x 4 x 4 over QQ[a ..a ]                 |
|                                                      0   3                  |
+-----------------------------------------------------------------------------+
|i2 : genericSkewMultidimensionalMatrix(3,4,CoefficientRing=>ZZ/101)          |
|                                                                             |
|o2 = {{{0, 0, 0, 0}, {0, 0, -a , -a }, {0, a , 0, -a }, {0, a , a , 0}}, {{0,|
|                              3    2        3       0        2   0           |
|     ------------------------------------------------------------------------|
|     0, a , a }, {0, 0, 0, 0}, {-a , 0, 0, -a }, {-a , 0, a , 0}}, {{0, -a , |
|         3   2                    3          1      2      1              3  |
|     ------------------------------------------------------------------------|
|     0, a }, {a , 0, 0, a }, {0, 0, 0, 0}, {-a , -a , 0, 0}}, {{0, -a , -a , |
|         0     3         1                    0    1                 2    0  |
|     ------------------------------------------------------------------------|
|     0}, {a , 0, -a , 0}, {a , a , 0, 0}, {0, 0, 0, 0}}}                     |
|           2       1        0   1                                            |
|                                                                             |
|                                                   ZZ                        |
|o2 : 3-dimensional matrix of shape 4 x 4 x 4 over ---[a ..a ]                |
|                                                  101  0   3                 |
+-----------------------------------------------------------------------------+
|i3 : genericSkewMultidimensionalMatrix(3,4,CoefficientRing=>ZZ/101,Variable=>|
|                                                                             |
|o3 = {{{0, 0, 0, 0}, {0, 0, -b , -b }, {0, b , 0, -b }, {0, b , b , 0}}, {{0,|
|                              1    0        1       2        0   2           |
|     ------------------------------------------------------------------------|
|     0, b , b }, {0, 0, 0, 0}, {-b , 0, 0, -b }, {-b , 0, b , 0}}, {{0, -b , |
|         1   0                    1          3      0      3              1  |
|     ------------------------------------------------------------------------|
|     0, b }, {b , 0, 0, b }, {0, 0, 0, 0}, {-b , -b , 0, 0}}, {{0, -b , -b , |
|         2     1         3                    2    3                 0    2  |
|     ------------------------------------------------------------------------|
|     0}, {b , 0, -b , 0}, {b , b , 0, 0}, {0, 0, 0, 0}}}                     |
|           0       3        2   3                                            |
|                                                                             |
|                                                   ZZ                        |
|o3 : 3-dimensional matrix of shape 4 x 4 x 4 over ---[b ..b ]                |
|                                                  101  0   3                 |
|-----------------------------------------------------------------------------|
|"b")                                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables
  * genericSymmetricMultidimensionalMatrix
    -- make a generic symmetric
    multidimensional matrix of variables

Ways to use genericSkewMultidimensionalMatrix :
===============================================

  * "genericSkewMultidimensionalMatrix(ZZ,ZZ)"

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

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

genericSymmetricMultidimensionalMatrix -- make a generic symmetric multidimensional matrix of variables
*******************************************************************************************************

Synopsis
========

  * Usage:
        genericSymmetricMultidimensionalMatrix(n,d)
  * Inputs:
      * (n,d), two positive integers.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value QQ
      * Variable => ..., default value "a"
  * Outputs:
      * the generic symmetric multidimensional matrix,
        of shape $d\times\cdots\times d$ ($n$ times).

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

An $n$-dimensional matrix $M$ is symmetric if for every permutation $s$ of the
set $\{0,\ldots,n-1\}$ we have permute,(M,s) == M.

+-----------------------------------------------------------------------------+
|i1 : genericSymmetricMultidimensionalMatrix(3,2)                             |
|                                                                             |
|o1 = {{{a , a }, {a , a }}, {{a , a }, {a , a }}}                            |
|         0   1     1   2       1   2     2   3                               |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 2 x 2 over QQ[a ..a ]                 |
|                                                      0   3                  |
+-----------------------------------------------------------------------------+
|i2 : genericSymmetricMultidimensionalMatrix(3,2,CoefficientRing=>ZZ/101)     |
|                                                                             |
|o2 = {{{a , a }, {a , a }}, {{a , a }, {a , a }}}                            |
|         0   1     1   2       1   2     2   3                               |
|                                                                             |
|                                                   ZZ                        |
|o2 : 3-dimensional matrix of shape 2 x 2 x 2 over ---[a ..a ]                |
|                                                  101  0   3                 |
+-----------------------------------------------------------------------------+
|i3 : genericSymmetricMultidimensionalMatrix(3,2,CoefficientRing=>ZZ/101,     |
|                                                                             |
|o3 = {{{b , b }, {b , b }}, {{b , b }, {b , b }}}                            |
|         0   1     1   2       1   2     2   3                               |
|                                                                             |
|                                                   ZZ                        |
|o3 : 3-dimensional matrix of shape 2 x 2 x 2 over ---[b ..b ]                |
|                                                  101  0   3                 |
|-----------------------------------------------------------------------------|
|Variable=>"b")                                                               |
+-----------------------------------------------------------------------------+

See also
========

  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables
  * genericSkewMultidimensionalMatrix,
    -- make a generic skew symmetric multidimensional matrix of variables

Ways to use genericSymmetricMultidimensionalMatrix :
====================================================

  * "genericSymmetricMultidimensionalMatrix(ZZ,ZZ)"

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

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

MultidimensionalMatrix -- the class of all multidimensional matrices
********************************************************************

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

A multidimensional matrix is a hyper-rectangular array of ring elements.

See also
========

  * multidimensionalMatrix -- make a
    multidimensional matrix

Functions and methods returning a multidimensional matrix :
===========================================================

  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables
  * genericSkewMultidimensionalMatrix,
    -- make a generic skew symmetric multidimensional matrix of variables
  * genericSymmetricMultidimensionalMatrix
    -- make a generic symmetric
    multidimensional matrix of variables
  * multidimensionalMatrix -- make a
    multidimensional matrix
  * randomMultidimensionalMatrix -- random
    multidimensional matrix

Methods that use a multidimensional matrix :
============================================

  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix
  * dim(MultidimensionalMatrix), --
    dimension of a multidimensional matrix
  * entries(MultidimensionalMatrix),
    -- lists the entries of a multidimensional matrix
  * "flattening(List,MultidimensionalMatrix)" -- see flattening,
    -- flattening of a multidimensional matrix
  * "flattening(ZZ,MultidimensionalMatrix)" -- see flattening,
    -- flattening of a multidimensional matrix
  * MultidimensionalMatrix * MultidimensionalMatrix
    -- product of
    multidimensional matrices
  * MultidimensionalMatrix + MultidimensionalMatrix
    -- sum of two
    multidimensional matrices of the same shape
  * MultidimensionalMatrix - MultidimensionalMatrix
    -- difference of two
    multidimensional matrices of the same shape
  * MultidimensionalMatrix == MultidimensionalMatrix
    -- equality of two
    multidimensional matrices
  * MultidimensionalMatrix _ Sequence
    -- get entry of multidimensional matrix
  * "permute(MultidimensionalMatrix,List)" -- see permute, --
    permute the dimensions of a multidimensional matrix
  * rank(MultidimensionalMatrix), --
    about the border rank of a multidimensional matrix
  * "reverseShape(MultidimensionalMatrix)" -- see reverseShape,
    -- reverse the dimensions of a multidimensional matrix
  * ring(MultidimensionalMatrix), --
    ring of a multidimensional matrix
  * RingElement * MultidimensionalMatrix
    -- product of a scalar with a multidimensional
    matrix
  * "shape(MultidimensionalMatrix)" -- see shape, -- shape of a
    multidimensional matrix
  * "sortShape(MultidimensionalMatrix)" -- see sortShape, --
    sort the dimensions of a multidimensional matrix
  * "sylvesterMatrix(MultidimensionalMatrix)" -- see sylvesterMatrix,
    -- Sylvester-type matrix for the hyperdeterminant of a
    matrix of boundary shape

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

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

multidimensionalMatrix -- make a multidimensional matrix
********************************************************

Synopsis
========

  * Usage:
        multidimensionalMatrix L
  * Inputs:
      * L, a list (Macaulay2Doc), a list of nested lists
        representing a hyper-rectangular array of ring elements.
  * Outputs:
      * a multidimensional matrix, the
        corresponding multidimensional matrix.

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

+-----------------------------------------------------------------------------+
|i1 : multidimensionalMatrix {{0, 5}, {9, 3}, {7, 2}}                         |
|                                                                             |
|o1 = {{0, 5}, {9, 3}, {7, 2}}                                                |
|                                                                             |
|o1 : 2-dimensional matrix of shape 3 x 2 over ZZ                             |
+-----------------------------------------------------------------------------+
|i2 : multidimensionalMatrix {{{1, 0}, {4, 3}}, {{3, 1}, {5, 9}}}             |
|                                                                             |
|o2 = {{{1, 0}, {4, 3}}, {{3, 1}, {5, 9}}}                                    |
|                                                                             |
|o2 : 3-dimensional matrix of shape 2 x 2 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+
|i3 : multidimensionalMatrix {{{7/3, 8, 0}, {6, 8, 3}}, {{3, 8, 2}, {9, 2, 4}}|
|                                                                             |
|        7                                                                    |
|o3 = {{{-, 8, 0}, {6, 8, 3}}, {{3, 8, 2}, {9, 2, 4}}, {{0, 2, 9}, {1, 9, 5}},|
|        3                                                                    |
|     ------------------------------------------------------------------------|
|     {{2, 8, 4}, {9, 7, 7}}}                                                 |
|                                                                             |
|o3 : 3-dimensional matrix of shape 4 x 2 x 3 over QQ                         |
|-----------------------------------------------------------------------------|
|, {{0, 2, 9}, {1, 9, 5}}, {{2, 8, 4}, {9, 7, 7}}}                            |
+-----------------------------------------------------------------------------+

See also
========

  * multidimensionalMatrix(RingElement)
    -- make a multidimensional matrix
    from a multilinear form
  * MultidimensionalMatrix -- the class of all
    multidimensional matrices
  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix
  * randomMultidimensionalMatrix -- random
    multidimensional matrix
  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables

Ways to use multidimensionalMatrix :
====================================

  * "multidimensionalMatrix(List)"
  * multidimensionalMatrix(RingElement)
    -- make a multidimensional matrix
    from a multilinear form

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

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

MultidimensionalMatrix * MultidimensionalMatrix -- product of multidimensional matrices
***************************************************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        M * N
  * Inputs:
      * M, a multidimensional matrix, a
        multidimensional matrix of shape $k_1\times\cdots\times k_r$
      * N, a multidimensional matrix, a
        multidimensional matrix of shape $l_1\times\cdots\times l_s$ with $k_r
        = l_1$
  * Outputs:
      * a multidimensional matrix, the
        convolution (or product) $M * N$, which is a multidimensional matrix of
        shape $k_1\times\cdots\times k_{r-1}\times l_2\times\cdots\times l_s$

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

+-----------------------------------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix {4,3}                                  |
|                                                                             |
|o1 = {{8, 1, 3}, {7, 8, 3}, {3, 7, 8}, {8, 5, 7}}                            |
|                                                                             |
|o1 : 2-dimensional matrix of shape 4 x 3 over ZZ                             |
+-----------------------------------------------------------------------------+
|i2 : N = randomMultidimensionalMatrix {3,2}                                  |
|                                                                             |
|o2 = {{8, 5}, {2, 3}, {6, 3}}                                                |
|                                                                             |
|o2 : 2-dimensional matrix of shape 3 x 2 over ZZ                             |
+-----------------------------------------------------------------------------+
|i3 : M * N                                                                   |
|                                                                             |
|o3 = {{84, 52}, {90, 68}, {86, 60}, {116, 76}}                               |
|                                                                             |
|o3 : 2-dimensional matrix of shape 4 x 2 over ZZ                             |
+-----------------------------------------------------------------------------+
|i4 : N' = randomMultidimensionalMatrix {3,2,4}                               |
|                                                                             |
|o4 = {{{6, 8, 6, 9}, {3, 7, 6, 9}}, {{6, 2, 6, 0}, {2, 6, 9, 3}}, {{5, 6, 3, |
|     ------------------------------------------------------------------------|
|     5}, {7, 7, 9, 4}}}                                                      |
|                                                                             |
|o4 : 3-dimensional matrix of shape 3 x 2 x 4 over ZZ                         |
+-----------------------------------------------------------------------------+
|i5 : M * N'                                                                  |
|                                                                             |
|o5 = {{{69, 84, 63, 87}, {47, 83, 84, 87}}, {{105, 90, 99, 78}, {58, 118,    |
|     ------------------------------------------------------------------------|
|     141, 99}}, {{100, 86, 84, 67}, {79, 119, 153, 80}}, {{113, 116, 99,     |
|     ------------------------------------------------------------------------|
|     107}, {83, 135, 156, 115}}}                                             |
|                                                                             |
|o5 : 3-dimensional matrix of shape 4 x 2 x 4 over ZZ                         |
+-----------------------------------------------------------------------------+

See also
========

  * RingElement * MultidimensionalMatrix
    -- product of a scalar with a multidimensional
    matrix

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

  * MultidimensionalMatrix * MultidimensionalMatrix
    -- product of
    multidimensional matrices

MultidimensionalMatrix + MultidimensionalMatrix -- sum of two multidimensional matrices of the same shape
*********************************************************************************************************

Synopsis
========

  * Operator: + (Macaulay2Doc),
  * Usage:
        M + N
  * Inputs:
      * M, a multidimensional matrix,
      * N, a multidimensional matrix,
  * Outputs:
      * a multidimensional matrix, the sum $M+N$

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4},  |
|                                                                             |
|o1 = {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4}, {8, 0}}}                    |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
|-----------------------------------------------------------------------------|
|{8, 0}}}                                                                     |
+-----------------------------------------------------------------------------+
|i2 : N = multidimensionalMatrix {{{1, 7}, {6, 5}, {5, 5}}, {{4, 3}, {3, 8},  |
|                                                                             |
|o2 = {{{1, 7}, {6, 5}, {5, 5}}, {{4, 3}, {3, 8}, {4, 1}}}                    |
|                                                                             |
|o2 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
|-----------------------------------------------------------------------------|
|{4, 1}}}                                                                     |
+-----------------------------------------------------------------------------+
|i3 : M + N                                                                   |
|                                                                             |
|o3 = {{{2, 14}, {9, 11}, {6, 11}}, {{7, 8}, {7, 12}, {12, 1}}}               |
|                                                                             |
|o3 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+

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

  * MultidimensionalMatrix + MultidimensionalMatrix
    -- sum of two
    multidimensional matrices of the same shape

MultidimensionalMatrix - MultidimensionalMatrix -- difference of two multidimensional matrices of the same shape
****************************************************************************************************************

Synopsis
========

  * Operator: - (Macaulay2Doc),
  * Usage:
        M - N
  * Inputs:
      * M, a multidimensional matrix,
      * N, a multidimensional matrix,
  * Outputs:
      * a multidimensional matrix, the
        difference $M-N$

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4},  |
|                                                                             |
|o1 = {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4}, {8, 0}}}                    |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
|-----------------------------------------------------------------------------|
|{8, 0}}}                                                                     |
+-----------------------------------------------------------------------------+
|i2 : N = multidimensionalMatrix {{{1, 7}, {6, 5}, {5, 5}}, {{4, 3}, {3, 8},  |
|                                                                             |
|o2 = {{{1, 7}, {6, 5}, {5, 5}}, {{4, 3}, {3, 8}, {4, 1}}}                    |
|                                                                             |
|o2 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
|-----------------------------------------------------------------------------|
|{4, 1}}}                                                                     |
+-----------------------------------------------------------------------------+
|i3 : M - N                                                                   |
|                                                                             |
|o3 = {{{0, 0}, {-3, 1}, {-4, 1}}, {{-1, 2}, {1, -4}, {4, -1}}}               |
|                                                                             |
|o3 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+
|i4 : -M                                                                      |
|                                                                             |
|o4 = {{{-1, -7}, {-3, -6}, {-1, -6}}, {{-3, -5}, {-4, -4}, {-8, 0}}}         |
|                                                                             |
|o4 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+

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

  * MultidimensionalMatrix - MultidimensionalMatrix
    -- difference of two
    multidimensional matrices of the same shape

MultidimensionalMatrix == MultidimensionalMatrix -- equality of two multidimensional matrices
*********************************************************************************************

Synopsis
========

  * Operator: == (Macaulay2Doc),
  * Usage:
        M == N
  * Inputs:
      * M, a multidimensional matrix,
      * N, a multidimensional matrix,
  * Outputs:
      * a Boolean value (Macaulay2Doc), true or false, depending
        on whether $M$ and $N$ are equal.

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

+---------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{7, 6}, {9, 3}, {1, 7}} |
|                                                         |
|o1 = {{7, 6}, {9, 3}, {1, 7}}                            |
|                                                         |
|o1 : 2-dimensional matrix of shape 3 x 2 over ZZ         |
+---------------------------------------------------------+
|i2 : N = multidimensionalMatrix {{7, 6}, {9, 4}, {1, 7}} |
|                                                         |
|o2 = {{7, 6}, {9, 4}, {1, 7}}                            |
|                                                         |
|o2 : 2-dimensional matrix of shape 3 x 2 over ZZ         |
+---------------------------------------------------------+
|i3 : N' = multidimensionalMatrix {{7, 6}, {9, 3}, {1, 7}}|
|                                                         |
|o3 = {{7, 6}, {9, 3}, {1, 7}}                            |
|                                                         |
|o3 : 2-dimensional matrix of shape 3 x 2 over ZZ         |
+---------------------------------------------------------+
|i4 : M == N                                              |
|                                                         |
|o4 = false                                               |
+---------------------------------------------------------+
|i5 : M == N'                                             |
|                                                         |
|o5 = true                                                |
+---------------------------------------------------------+
|i6 : M - N' == 0                                         |
|                                                         |
|o6 = true                                                |
+---------------------------------------------------------+

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

  * MultidimensionalMatrix == MultidimensionalMatrix
    -- equality of two
    multidimensional matrices

MultidimensionalMatrix _ Sequence -- get entry of multidimensional matrix
*************************************************************************

Synopsis
========

  * Operator: _ (Macaulay2Doc),
  * Usage:
        M_l
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix.
      * l, a sequence (Macaulay2Doc), a sequence of $n$
        nonnegative integers.
  * Outputs:
      * a ring element (Macaulay2Doc), the $l$-th entry of
        the matrix $M$ (note that indexes start from 0).

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

+-----------------------------------------------------------------------------+
|i1 : M = genericMultidimensionalMatrix {2,3,2}                               |
|                                                                             |
|o1 = {{{a     , a     }, {a     , a     }, {a     , a     }}, {{a     ,      |
|         0,0,0   0,0,1     0,1,0   0,1,1     0,2,0   0,2,1       1,0,0       |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }, {a     , a     }}}                           |
|      1,0,1     1,1,0   1,1,1     1,2,0   1,2,1                              |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ[a     ..a     ]         |
|                                                      0,0,0   1,2,1          |
+-----------------------------------------------------------------------------+
|i2 : M_(1,2,0)                                                               |
|                                                                             |
|o2 = a                                                                       |
|      1,2,0                                                                  |
|                                                                             |
|o2 : ZZ[a     ..a     ]                                                      |
|         0,0,0   1,2,1                                                       |
+-----------------------------------------------------------------------------+

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

  * MultidimensionalMatrix _ Sequence
    -- get entry of multidimensional matrix

multidimensionalMatrix(RingElement) -- make a multidimensional matrix from a multilinear form
*********************************************************************************************

Synopsis
========

  * Function: multidimensionalMatrix,
  * Usage:
        multidimensionalMatrix F
  * Inputs:
      * F, a ring element (Macaulay2Doc), a homogeneous
        polynomial of multidegree $(1,\ldots,1)$ in a polynomial ring $R$ with
        the $\mathbb{Z}^n$-grading where the degree of each variable is a
        standard basis vector; in other words, $R$ is the homogeneous
        coordinate ring of a product of $n$ projective spaces.
  * Outputs:
      * a multidimensional matrix, the
        $n$-dimensional matrix having as entries the coefficients of $F$.

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

If $F$ is a multilinear form on
$\mathbb{P}^{k_1}\times\mathbb{P}^{k_2}\times\cdots\times\mathbb{P}^{k_n}$,
then the shape of the corresponding matrix is
$(k_1+1)\times(k_2+1)\times\cdots\times(k_n+1)$. You can use permute,
to rearrange the dimensions.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ[x_1..x_3,y_1..y_4,z_1..z_2,Degrees=>{3:{1,0,0},4:{0,1,0},2:{0,0,1|
|-----------------------------------------------------------------------------|
|}}];                                                                         |
+-----------------------------------------------------------------------------+
|i2 : F = random({1,1,1},R)                                                   |
|                                                                             |
|o2 = 8x y z  + 8x y z  + 6x y z  + 3x y z  + 5x y z  + 6x y z  + 8x y z  +   |
|       1 1 1     2 1 1     3 1 1     1 2 1     2 2 1     3 2 1     1 3 1     |
|     ------------------------------------------------------------------------|
|     8x y z  + 6x y z  + 3x y z  + 2x y z  + 3x y z  + x y z  + 8x y z  +    |
|       2 3 1     3 3 1     1 4 1     2 4 1     3 4 1    1 1 2     2 1 2      |
|     ------------------------------------------------------------------------|
|     3x y z  + 7x y z  + 7x y z  + 8x y z  + 3x y z  + 5x y z  + 9x y z  +   |
|       3 1 2     1 2 2     2 2 2     3 2 2     1 3 2     2 3 2     3 3 2     |
|     ------------------------------------------------------------------------|
|     7x y z  + 3x y z  + 7x y z                                              |
|       1 4 2     2 4 2     3 4 2                                             |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : M = multidimensionalMatrix F                                            |
|                                                                             |
|o3 = {{{8, 1}, {3, 7}, {8, 3}, {3, 7}}, {{8, 8}, {5, 7}, {8, 5}, {2, 3}},    |
|     ------------------------------------------------------------------------|
|     {{6, 3}, {6, 8}, {6, 9}, {3, 7}}}                                       |
|                                                                             |
|o3 : 3-dimensional matrix of shape 3 x 4 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+

The inverse operation can be obtained using the command "!" as follows:

+-----------------------------------------------------------------------------+
|i4 : F' = M!                                                                 |
|                                                                             |
|o4 = 8x0 x1 x2  + 8x0 x1 x2  + 6x0 x1 x2  + 3x0 x1 x2  + 5x0 x1 x2  +        |
|        0  0  0      1  0  0      2  0  0      0  1  0      1  1  0          |
|     ------------------------------------------------------------------------|
|     6x0 x1 x2  + 8x0 x1 x2  + 8x0 x1 x2  + 6x0 x1 x2  + 3x0 x1 x2  +        |
|        2  1  0      0  2  0      1  2  0      2  2  0      0  3  0          |
|     ------------------------------------------------------------------------|
|     2x0 x1 x2  + 3x0 x1 x2  + x0 x1 x2  + 8x0 x1 x2  + 3x0 x1 x2  +         |
|        1  3  0      2  3  0     0  0  1      1  0  1      2  0  1           |
|     ------------------------------------------------------------------------|
|     7x0 x1 x2  + 7x0 x1 x2  + 8x0 x1 x2  + 3x0 x1 x2  + 5x0 x1 x2  +        |
|        0  1  1      1  1  1      2  1  1      0  2  1      1  2  1          |
|     ------------------------------------------------------------------------|
|     9x0 x1 x2  + 7x0 x1 x2  + 3x0 x1 x2  + 7x0 x1 x2                        |
|        2  2  1      0  3  1      1  3  1      2  3  1                       |
|                                                                             |
|o4 : ZZ[x0 ..x0 , x1 ..x1 , x2 ..x2 ]                                        |
|          0    2    0    3    0    1                                         |
+-----------------------------------------------------------------------------+
|i5 : assert(M === multidimensionalMatrix F')                                 |
+-----------------------------------------------------------------------------+
|i6 : assert(sub(F',vars ring F) === F)                                       |
+-----------------------------------------------------------------------------+

See also
========

  * multidimensionalMatrix(List) -- make a
    multidimensional matrix
  * MultidimensionalMatrix -- the class of all
    multidimensional matrices

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

  * multidimensionalMatrix(RingElement)
    -- make a multidimensional matrix
    from a multilinear form

permute -- permute the dimensions of a multidimensional matrix
**************************************************************

Synopsis
========

  * Usage:
        permute(M,s)
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix.
      * s, a list (Macaulay2Doc), a permutation of the set
        $\{0,1,\ldots,n-1\}$.
  * Outputs:
      * a multidimensional matrix, with the same
        entries as the input, but with the dimensions re-ordered according to
        the specified permutation.

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

According to the definition given on page 449 of the book Discriminants,
Resultants, and Multidimensional Determinants (see
http://link.springer.com/book/10.1007%2F978-0-8176-4771-1 ), the output of this
method is $s'(M)$, where $s'$ is the inverse permutation of $s$.

+-----------------------------------------------------------------------------+
|i1 : M = genericMultidimensionalMatrix {4,3,2}                               |
|                                                                             |
|o1 = {{{a     , a     }, {a     , a     }, {a     , a     }}, {{a     ,      |
|         0,0,0   0,0,1     0,1,0   0,1,1     0,2,0   0,2,1       1,0,0       |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }, {a     , a     }}, {{a     , a     },        |
|      1,0,1     1,1,0   1,1,1     1,2,0   1,2,1       2,0,0   2,0,1          |
|     ------------------------------------------------------------------------|
|     {a     , a     }, {a     , a     }}, {{a     , a     }, {a     ,        |
|       2,1,0   2,1,1     2,2,0   2,2,1       3,0,0   3,0,1     3,1,0         |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }}}                                             |
|      3,1,1     3,2,0   3,2,1                                                |
|                                                                             |
|o1 : 3-dimensional matrix of shape 4 x 3 x 2 over ZZ[a     ..a     ]         |
|                                                      0,0,0   3,2,1          |
+-----------------------------------------------------------------------------+
|i2 : permute(M,{1,0,2})                                                      |
|                                                                             |
|o2 = {{{a     , a     }, {a     , a     }, {a     , a     }, {a     ,        |
|         0,0,0   0,0,1     1,0,0   1,0,1     2,0,0   2,0,1     3,0,0         |
|     ------------------------------------------------------------------------|
|     a     }}, {{a     , a     }, {a     , a     }, {a     , a     },        |
|      3,0,1       0,1,0   0,1,1     1,1,0   1,1,1     2,1,0   2,1,1          |
|     ------------------------------------------------------------------------|
|     {a     , a     }}, {{a     , a     }, {a     , a     }, {a     ,        |
|       3,1,0   3,1,1       0,2,0   0,2,1     1,2,0   1,2,1     2,2,0         |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }}}                                             |
|      2,2,1     3,2,0   3,2,1                                                |
|                                                                             |
|o2 : 3-dimensional matrix of shape 3 x 4 x 2 over ZZ[a     ..a     ]         |
|                                                      0,0,0   3,2,1          |
+-----------------------------------------------------------------------------+
|i3 : permute(M,{2,0,1})                                                      |
|                                                                             |
|o3 = {{{a     , a     , a     }, {a     , a     , a     }, {a     , a     ,  |
|         0,0,0   0,1,0   0,2,0     1,0,0   1,1,0   1,2,0     2,0,0   2,1,0   |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     , a     }}, {{a     , a     , a     }, {a     , |
|      2,2,0     3,0,0   3,1,0   3,2,0       0,0,1   0,1,1   0,2,1     1,0,1  |
|     ------------------------------------------------------------------------|
|     a     , a     }, {a     , a     , a     }, {a     , a     , a     }}}   |
|      1,1,1   1,2,1     2,0,1   2,1,1   2,2,1     3,0,1   3,1,1   3,2,1      |
|                                                                             |
|o3 : 3-dimensional matrix of shape 2 x 4 x 3 over ZZ[a     ..a     ]         |
|                                                      0,0,0   3,2,1          |
+-----------------------------------------------------------------------------+

See also
========

  * reverseShape -- reverse the dimensions of a
    multidimensional matrix
  * sortShape -- sort the dimensions of a multidimensional
    matrix
  * transpose (Macaulay2Doc) -- transpose a table or a matrix

Ways to use permute :
=====================

  * "permute(MultidimensionalMatrix,List)"

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

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

randomMultidimensionalMatrix -- random multidimensional matrix
**************************************************************

Synopsis
========

  * Usage:
        randomMultidimensionalMatrix(d_1,...,d_n)
  * Inputs:
      * (d_1,...,d_n), a sequence of positive integers.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
      * MaximalRank => ..., default value null
  * Outputs:
      * a random multidimensional matrix, of
        shape $d_1\times\cdots\times d_n$ over the ring specified by the option
        CoefficientRing, (the default ring
        is ZZ (Macaulay2Doc)).

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

+-----------------------------------------------------------------------------+
|i1 : randomMultidimensionalMatrix(2,4,3)                                     |
|                                                                             |
|o1 = {{{8, 1, 3}, {7, 8, 3}, {3, 7, 8}, {8, 5, 7}}, {{8, 5, 2}, {3, 6, 3},   |
|     ------------------------------------------------------------------------|
|     {6, 8, 6}, {9, 3, 7}}}                                                  |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 4 x 3 over ZZ                         |
+-----------------------------------------------------------------------------+
|i2 : randomMultidimensionalMatrix((2,2,3),CoefficientRing=>ZZ/101)           |
|                                                                             |
|o2 = {{{-47, 38, 2}, {16, 22, 45}}, {{-34, -48, -47}, {47, 19, -16}}}        |
|                                                                             |
|                                                   ZZ                        |
|o2 : 3-dimensional matrix of shape 2 x 2 x 3 over ---                        |
|                                                  101                        |
+-----------------------------------------------------------------------------+

See also
========

  * genericMultidimensionalMatrix -- make
    a generic multidimensional matrix of variables

Ways to use randomMultidimensionalMatrix :
==========================================

  * "randomMultidimensionalMatrix(VisibleList)"

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

The object randomMultidimensionalMatrix, is
a method function with a single argument (Macaulay2Doc).

rank(MultidimensionalMatrix) -- about the border rank of a multidimensional matrix
**********************************************************************************

Synopsis
========

  * Function: rank (Macaulay2Doc),
  * Usage:
        rank M
  * Inputs:
      * M, a multidimensional matrix,
  * Outputs:
      * an integer (Macaulay2Doc), a lower bound for the (border)
        rank of M, which is calculated as the maximum rank of all the
        flattenings, of M

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

In some cases, we know that the returned integer r = rank M is exactly the
border rank of M. For instance, this is the case if r<3 by a result of C. Raicu
(see https://arxiv.org/abs/1011.5867v2 ). In general, however, we obtain only a
lower bound and it is not known how to calculate this rank exactly without
resorting to elimination.

+-----------------------------------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix(2,4,3,2,MaximalRank=>2)                |
|                                                                             |
|o1 = {{{{1206, 1305}, {2604, 2730}, {3216, 3480}}, {{1596, 1218}, {3640,     |
|     ------------------------------------------------------------------------|
|     2716}, {4256, 3248}}, {{1914, 1527}, {4340, 3374}, {5104, 4072}},       |
|     ------------------------------------------------------------------------|
|     {{1332, 1494}, {2856, 3108}, {3552, 3984}}}, {{{792, 1125}, {1608,      |
|     ------------------------------------------------------------------------|
|     2265}, {2112, 3000}}, {{456, 537}, {968, 1109}, {1216, 1432}}, {{624,   |
|     ------------------------------------------------------------------------|
|     768}, {1312, 1576}, {1664, 2048}}, {{936, 1341}, {1896, 2697}, {2496,   |
|     ------------------------------------------------------------------------|
|     3576}}}}                                                                |
|                                                                             |
|o1 : 4-dimensional matrix of shape 2 x 4 x 3 x 2 over ZZ                     |
+-----------------------------------------------------------------------------+
|i2 : rank M                                                                  |
|                                                                             |
|o2 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i3 : M' = randomMultidimensionalMatrix(2,4,2,1,3,CoefficientRing=>ZZ/65521,Ma|
|                                                                             |
|o3 = {{{{{12579, 2823, -26362}}, {{-20238, 21337, -29331}}}, {{{12274, 29536,|
|     ------------------------------------------------------------------------|
|     -1718}}, {{-25383, -8569, -19467}}}, {{{32013, -11709, 1349}}, {{-661,  |
|     ------------------------------------------------------------------------|
|     18457, -14503}}}, {{{25956, 4878, -11219}}, {{-25462, 3917, -21610}}}}, |
|     ------------------------------------------------------------------------|
|     {{{{-7660, 24925, 19945}}, {{-16591, 30427, 29978}}}, {{{-8163, -32551, |
|     ------------------------------------------------------------------------|
|     14558}}, {{4616, -11937, -26503}}}, {{{12391, -10012, -10837}}, {{11758,|
|     ------------------------------------------------------------------------|
|     -3760, -17677}}}, {{{9920, -29378, 29772}}, {{25674, -4729, 12002}}}}}  |
|                                                                             |
|                                                            ZZ               |
|o3 : 5-dimensional matrix of shape 2 x 4 x 2 x 1 x 3 over -----              |
|                                                          65521              |
|-----------------------------------------------------------------------------|
|ximalRank=>4)                                                                |
+-----------------------------------------------------------------------------+
|i4 : rank M'                                                                 |
|                                                                             |
|o4 = 4                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * flattening -- flattening of a multidimensional matrix
  * randomMultidimensionalMatrix -- random
    multidimensional matrix

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

  * rank(MultidimensionalMatrix), --
    about the border rank of a multidimensional matrix

reverseShape -- reverse the dimensions of a multidimensional matrix
*******************************************************************

Synopsis
========

  * Usage:
        reverseShape M
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix.
  * Outputs:
      * a multidimensional matrix, the same as
        permute,(M,{n-1,...,1,0}).

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

+-----------------------------------------------------------------------------+
|i1 : M = genericMultidimensionalMatrix {4,3,2}                               |
|                                                                             |
|o1 = {{{a     , a     }, {a     , a     }, {a     , a     }}, {{a     ,      |
|         0,0,0   0,0,1     0,1,0   0,1,1     0,2,0   0,2,1       1,0,0       |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }, {a     , a     }}, {{a     , a     },        |
|      1,0,1     1,1,0   1,1,1     1,2,0   1,2,1       2,0,0   2,0,1          |
|     ------------------------------------------------------------------------|
|     {a     , a     }, {a     , a     }}, {{a     , a     }, {a     ,        |
|       2,1,0   2,1,1     2,2,0   2,2,1       3,0,0   3,0,1     3,1,0         |
|     ------------------------------------------------------------------------|
|     a     }, {a     , a     }}}                                             |
|      3,1,1     3,2,0   3,2,1                                                |
|                                                                             |
|o1 : 3-dimensional matrix of shape 4 x 3 x 2 over ZZ[a     ..a     ]         |
|                                                      0,0,0   3,2,1          |
+-----------------------------------------------------------------------------+
|i2 : reverseShape M                                                          |
|                                                                             |
|o2 = {{{a     , a     , a     , a     }, {a     , a     , a     , a     },   |
|         0,0,0   1,0,0   2,0,0   3,0,0     0,1,0   1,1,0   2,1,0   3,1,0     |
|     ------------------------------------------------------------------------|
|     {a     , a     , a     , a     }}, {{a     , a     , a     , a     },   |
|       0,2,0   1,2,0   2,2,0   3,2,0       0,0,1   1,0,1   2,0,1   3,0,1     |
|     ------------------------------------------------------------------------|
|     {a     , a     , a     , a     }, {a     , a     , a     , a     }}}    |
|       0,1,1   1,1,1   2,1,1   3,1,1     0,2,1   1,2,1   2,2,1   3,2,1       |
|                                                                             |
|o2 : 3-dimensional matrix of shape 2 x 3 x 4 over ZZ[a     ..a     ]         |
|                                                      0,0,0   3,2,1          |
+-----------------------------------------------------------------------------+
|i3 : assert(M === reverseShape reverseShape M)                               |
+-----------------------------------------------------------------------------+

See also
========

  * permute -- permute the dimensions of a multidimensional
    matrix
  * sortShape -- sort the dimensions of a multidimensional
    matrix
  * transpose (Macaulay2Doc) -- transpose a table or a matrix

Ways to use reverseShape :
==========================

  * "reverseShape(MultidimensionalMatrix)"

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

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

ring(MultidimensionalMatrix) -- ring of a multidimensional matrix
*****************************************************************

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring M
  * Inputs:
      * M, a multidimensional matrix,
  * Outputs:
      * a ring (Macaulay2Doc), the common ring of the entries of M

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{3, 8}, {3, 6}}, {{5, 1}, {4, 2}}}         |
|                                                                             |
|o1 = {{{3, 8}, {3, 6}}, {{5, 1}, {4, 2}}}                                    |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 2 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+
|i2 : ring M                                                                  |
|                                                                             |
|o2 = ZZ                                                                      |
|                                                                             |
|o2 : Ring                                                                    |
+-----------------------------------------------------------------------------+
|i3 : M = multidimensionalMatrix {{{7, 2/3}, {1/7, 3}}, {{5/8, 8/9}, {1/3,    |
|                                                                             |
|           2    1         5  8    1                                          |
|o3 = {{{7, -}, {-, 3}}, {{-, -}, {-, 5}}}                                    |
|           3    7         8  9    3                                          |
|                                                                             |
|o3 : 3-dimensional matrix of shape 2 x 2 x 2 over QQ                         |
|-----------------------------------------------------------------------------|
|5}}}                                                                         |
+-----------------------------------------------------------------------------+
|i4 : ring M                                                                  |
|                                                                             |
|o4 = QQ                                                                      |
|                                                                             |
|o4 : Ring                                                                    |
+-----------------------------------------------------------------------------+

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

  * ring(MultidimensionalMatrix), --
    ring of a multidimensional matrix

RingElement * MultidimensionalMatrix -- product of a scalar with a multidimensional matrix
******************************************************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        e * N
  * Inputs:
      * e, a ring element (Macaulay2Doc),
      * M, a multidimensional matrix,
  * Outputs:
      * a multidimensional matrix, the product
        $e*M$

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4},  |
|                                                                             |
|o1 = {{{1, 7}, {3, 6}, {1, 6}}, {{3, 5}, {4, 4}, {8, 0}}}                    |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
|-----------------------------------------------------------------------------|
|{8, 0}}}                                                                     |
+-----------------------------------------------------------------------------+
|i2 : 2 * M                                                                   |
|                                                                             |
|o2 = {{{2, 14}, {6, 12}, {2, 12}}, {{6, 10}, {8, 8}, {16, 0}}}               |
|                                                                             |
|o2 : 3-dimensional matrix of shape 2 x 3 x 2 over ZZ                         |
+-----------------------------------------------------------------------------+
|i3 : (3/2) * M                                                               |
|                                                                             |
|        3  21    9       3         9  15                                     |
|o3 = {{{-, --}, {-, 9}, {-, 9}}, {{-, --}, {6, 6}, {12, 0}}}                 |
|        2   2    2       2         2   2                                     |
|                                                                             |
|o3 : 3-dimensional matrix of shape 2 x 3 x 2 over QQ                         |
+-----------------------------------------------------------------------------+

See also
========

  * MultidimensionalMatrix * MultidimensionalMatrix
    -- product of
    multidimensional matrices

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

  * RingElement * MultidimensionalMatrix
    -- product of a scalar with a multidimensional
    matrix

shape -- shape of a multidimensional matrix
*******************************************

Synopsis
========

  * Usage:
        shape M
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix of shape $k_1\times\cdots\times k_n$
  * Outputs:
      * a list (Macaulay2Doc), the list of integers $\{k_1, \ldots,
        k_n\}$

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

+-----------------------------------------------------------------------------+
|i1 : M = multidimensionalMatrix {{{0, 8, 3}, {7, 3, 2}, {2, 7, 0}, {4, 8, 4}}|
|                                                                             |
|o1 = {{{0, 8, 3}, {7, 3, 2}, {2, 7, 0}, {4, 8, 4}}, {{0, 8, 1}, {3, 1, 0},   |
|     ------------------------------------------------------------------------|
|     {4, 7, 4}, {0, 6, 9}}}                                                  |
|                                                                             |
|o1 : 3-dimensional matrix of shape 2 x 4 x 3 over ZZ                         |
|-----------------------------------------------------------------------------|
|, {{0, 8, 1}, {3, 1, 0}, {4, 7, 4}, {0, 6, 9}}}                              |
+-----------------------------------------------------------------------------+
|i2 : shape M                                                                 |
|                                                                             |
|o2 = {2, 4, 3}                                                               |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * dim(MultidimensionalMatrix), --
    dimension of a multidimensional matrix

Ways to use shape :
===================

  * "shape(MultidimensionalMatrix)"

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

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

sortShape -- sort the dimensions of a multidimensional matrix
*************************************************************

Synopsis
========

  * Usage:
        sortShape M
  * Inputs:
      * M, a multidimensional matrix,
  * Outputs:
      * a multidimensional matrix, the same as
        permute,(M,s), where s is the sorting permutation of the
        shape of M.

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

+-----------------------------------------------------------------------------+
|i1 : M = genericMultidimensionalMatrix {4,1,3,2}                             |
|                                                                             |
|o1 = {{{{a       , a       }, {a       , a       }, {a       , a       }}},  |
|          0,0,0,0   0,0,0,1     0,0,1,0   0,0,1,1     0,0,2,0   0,0,2,1      |
|     ------------------------------------------------------------------------|
|     {{{a       , a       }, {a       , a       }, {a       , a       }}},   |
|         1,0,0,0   1,0,0,1     1,0,1,0   1,0,1,1     1,0,2,0   1,0,2,1       |
|     ------------------------------------------------------------------------|
|     {{{a       , a       }, {a       , a       }, {a       , a       }}},   |
|         2,0,0,0   2,0,0,1     2,0,1,0   2,0,1,1     2,0,2,0   2,0,2,1       |
|     ------------------------------------------------------------------------|
|     {{{a       , a       }, {a       , a       }, {a       , a       }}}}   |
|         3,0,0,0   3,0,0,1     3,0,1,0   3,0,1,1     3,0,2,0   3,0,2,1       |
|                                                                             |
|o1 : 4-dimensional matrix of shape 4 x 1 x 3 x 2 over ZZ[a       ..a       ] |
|                                                          0,0,0,0   3,0,2,1  |
+-----------------------------------------------------------------------------+
|i2 : sortShape M                                                             |
|                                                                             |
|o2 = {{{{a       , a       , a       , a       }, {a       , a       ,       |
|          0,0,0,0   1,0,0,0   2,0,0,0   3,0,0,0     0,0,1,0   1,0,1,0        |
|     ------------------------------------------------------------------------|
|     a       , a       }, {a       , a       , a       , a       }},         |
|      2,0,1,0   3,0,1,0     0,0,2,0   1,0,2,0   2,0,2,0   3,0,2,0            |
|     ------------------------------------------------------------------------|
|     {{a       , a       , a       , a       }, {a       , a       ,         |
|        0,0,0,1   1,0,0,1   2,0,0,1   3,0,0,1     0,0,1,1   1,0,1,1          |
|     ------------------------------------------------------------------------|
|     a       , a       }, {a       , a       , a       , a       }}}}        |
|      2,0,1,1   3,0,1,1     0,0,2,1   1,0,2,1   2,0,2,1   3,0,2,1            |
|                                                                             |
|o2 : 4-dimensional matrix of shape 1 x 2 x 3 x 4 over ZZ[a       ..a       ] |
|                                                          0,0,0,0   3,0,2,1  |
+-----------------------------------------------------------------------------+
|i3 : assert(sortShape M === permute(M,{1,3,2,0}))                            |
+-----------------------------------------------------------------------------+

See also
========

  * permute -- permute the dimensions of a multidimensional
    matrix
  * reverseShape -- reverse the dimensions of a
    multidimensional matrix
  * transpose (Macaulay2Doc) -- transpose a table or a matrix

Ways to use sortShape :
=======================

  * "sortShape(MultidimensionalMatrix)"

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

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

SparseDiscriminant -- the class of all sparse discriminants
***********************************************************

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

An object of this class is created by the method sparseDiscriminant,
when the input is an integral matrix $A$ with $n$ rows.
Such an object behaves like a function that to a Laurent polynomial $f$ in $n$
variables $x=(x_1,\ldots,x_n)$, with $f = \sum_{\omega\in \{columns\ of\ A\}}
a_{\omega} x^{\omega}$, associates its sparse discriminant $Disc_{A}(f)$, which
is a polynomial in the coefficients $a_{\omega}$. An error is thrown if the
polynomial $f$ does not have the correct form.

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

  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)

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

  * char(SparseDiscriminant) -- get the
    characteristic
  * exponents(SparseDiscriminant), --
    get the matrix of exponents
  * SparseDiscriminant Thing -- evaluate a
    sparse discriminant

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

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

sparseDiscriminant -- sparse discriminant (A-discriminant)
**********************************************************

Synopsis
========

  * Usage:
        sparseDiscriminant A
  * Inputs:
      * A, a matrix (Macaulay2Doc), a matrix over $\mathbb{Z}$
        with $n$ rows to represent the exponent vectors of a Laurent polynomial
        $f$ in $n$ variables, $f = \sum_{\omega\in A} a_{\omega} x^{\omega}$.
        If one wants to perform computations only in characteristic $p>0$, then
        it is recommended to use the option CoefficientRing=>ZZ/p.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
  * Outputs:
      * an instance of the type SparseDiscriminant,
        the universal sparse discriminant associated to $A$, that is, a
        function that to a Laurent polynomial $f$ in $n$ variables over a
        coefficient ring $K$, involving only monomials from $A$, associates the
        sparse discriminant of $f$, which is an element of $K$.

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

Alternatively, one can apply the method directly to the Laurent polynomial $f$.
In this case, the matrix $A$ is automatically determined by
exponentsMatrix.

As an example, we now calculate the sparse discriminant of a generic trilinear
form on $\mathbb{P}^1\times\mathbb{P}^2\times \mathbb{P}^1$, that is, the
hyperdeterminant of a generic three-dimensional matrix of shape $2\times
3\times 2$.

+-----------------------------------------------------------------------------+
|i1 : f = genericMultihomogeneousPolynomial((2,3,2),(1,1,1))                  |
|                                                                             |
|o1 = a     x y z  + a     x y z  + a     x y z  + a     x y z  + a     x y z |
|      0,0,0 0 0 0    0,0,1 0 0 1    0,1,0 0 1 0    0,1,1 0 1 1    0,2,0 0 2 0|
|     ------------------------------------------------------------------------|
|     + a     x y z  + a     x y z  + a     x y z  + a     x y z  +           |
|        0,2,1 0 2 1    1,0,0 1 0 0    1,0,1 1 0 1    1,1,0 1 1 0             |
|     ------------------------------------------------------------------------|
|     a     x y z  + a     x y z  + a     x y z                               |
|      1,1,1 1 1 1    1,2,0 1 2 0    1,2,1 1 2 1                              |
|                                                                             |
|o1 : ZZ[a     ..a     ][x ..x , y ..y , z ..z ]                              |
|         0,0,0   1,2,1   0   1   0   2   0   1                               |
+-----------------------------------------------------------------------------+
|i2 : time sparseDiscriminant f                                               |
|     -- used 5.44235 seconds                                                 |
|                                                                             |
|                                                   2                         |
|o2 = a     a     a     a     a     a      - a     a     a     a     a      - |
|      0,1,1 0,2,0 0,2,1 1,0,0 1,0,1 1,1,0    0,1,0 0,2,1 1,0,0 1,0,1 1,1,0   |
|     ------------------------------------------------------------------------|
|            2     2                                2                         |
|     a     a     a     a      + a     a     a     a     a      -             |
|      0,1,1 0,2,0 1,0,1 1,1,0    0,1,0 0,2,0 0,2,1 1,0,1 1,1,0               |
|     ------------------------------------------------------------------------|
|                              2              2           2                   |
|     a     a     a     a     a      + a     a     a     a      -             |
|      0,0,1 0,2,0 0,2,1 1,0,1 1,1,0    0,0,0 0,2,1 1,0,1 1,1,0               |
|     ------------------------------------------------------------------------|
|                        2                    2     2                         |
|     a     a     a     a     a      + a     a     a     a      +             |
|      0,1,1 0,2,0 0,2,1 1,0,0 1,1,1    0,1,0 0,2,1 1,0,0 1,1,1               |
|     ------------------------------------------------------------------------|
|            2                                                                |
|     a     a     a     a     a      - a     a     a     a     a     a      + |
|      0,1,1 0,2,0 1,0,0 1,0,1 1,1,1    0,1,0 0,2,0 0,2,1 1,0,0 1,0,1 1,1,1   |
|     ------------------------------------------------------------------------|
|                                                   2                         |
|     a     a     a     a     a     a      - a     a     a     a     a      + |
|      0,0,1 0,2,0 0,2,1 1,0,0 1,1,0 1,1,1    0,0,0 0,2,1 1,0,0 1,1,0 1,1,1   |
|     ------------------------------------------------------------------------|
|            2                                                                |
|     a     a     a     a     a      - a     a     a     a     a     a      - |
|      0,0,1 0,2,0 1,0,1 1,1,0 1,1,1    0,0,0 0,2,0 0,2,1 1,0,1 1,1,0 1,1,1   |
|     ------------------------------------------------------------------------|
|            2           2                                2                   |
|     a     a     a     a      + a     a     a     a     a      -             |
|      0,0,1 0,2,0 1,0,0 1,1,1    0,0,0 0,2,0 0,2,1 1,0,0 1,1,1               |
|     ------------------------------------------------------------------------|
|      2                                                                      |
|     a     a     a     a     a      + a     a     a     a     a     a      + |
|      0,1,1 0,2,0 1,0,0 1,0,1 1,2,0    0,1,0 0,1,1 0,2,1 1,0,0 1,0,1 1,2,0   |
|     ------------------------------------------------------------------------|
|                        2              2           2                         |
|     a     a     a     a     a      - a     a     a     a      +             |
|      0,1,0 0,1,1 0,2,0 1,0,1 1,2,0    0,1,0 0,2,1 1,0,1 1,2,0               |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      +                                  |
|      0,0,1 0,1,1 0,2,0 1,0,1 1,1,0 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,1 0,1,0 0,2,1 1,0,1 1,1,0 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     2a     a     a     a     a     a      +                                 |
|       0,0,0 0,1,1 0,2,1 1,0,1 1,1,0 1,2,0                                   |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,1 0,1,1 0,2,0 1,0,0 1,1,1 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     2a     a     a     a     a     a      +                                 |
|       0,0,1 0,1,0 0,2,1 1,0,0 1,1,1 1,2,0                                   |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,0 0,1,1 0,2,1 1,0,0 1,1,1 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,1 0,1,0 0,2,0 1,0,1 1,1,1 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      +                                  |
|      0,0,0 0,1,1 0,2,0 1,0,1 1,1,1 1,2,0                                    |
|     ------------------------------------------------------------------------|
|                                              2                              |
|     2a     a     a     a     a     a      - a     a     a     a     a      +|
|       0,0,0 0,1,0 0,2,1 1,0,1 1,1,1 1,2,0    0,0,1 0,2,0 1,1,0 1,1,1 1,2,0  |
|     ------------------------------------------------------------------------|
|                                                               2             |
|     a     a     a     a     a     a      + a     a     a     a     a      - |
|      0,0,0 0,0,1 0,2,1 1,1,0 1,1,1 1,2,0    0,0,0 0,0,1 0,2,0 1,1,1 1,2,0   |
|     ------------------------------------------------------------------------|
|      2           2                                      2                   |
|     a     a     a     a      - a     a     a     a     a      +             |
|      0,0,0 0,2,1 1,1,1 1,2,0    0,0,1 0,1,0 0,1,1 1,0,1 1,2,0               |
|     ------------------------------------------------------------------------|
|            2           2        2                 2                         |
|     a     a     a     a      + a     a     a     a      -                   |
|      0,0,0 0,1,1 1,0,1 1,2,0    0,0,1 0,1,0 1,1,1 1,2,0                     |
|     ------------------------------------------------------------------------|
|                              2        2           2                         |
|     a     a     a     a     a      + a     a     a     a      -             |
|      0,0,0 0,0,1 0,1,1 1,1,1 1,2,0    0,1,1 0,2,0 1,0,0 1,2,1               |
|     ------------------------------------------------------------------------|
|                        2                                                    |
|     a     a     a     a     a      - a     a     a     a     a     a      + |
|      0,1,0 0,1,1 0,2,1 1,0,0 1,2,1    0,1,0 0,1,1 0,2,0 1,0,0 1,0,1 1,2,1   |
|     ------------------------------------------------------------------------|
|      2                                                                      |
|     a     a     a     a     a      - 2a     a     a     a     a     a      +|
|      0,1,0 0,2,1 1,0,0 1,0,1 1,2,1     0,0,1 0,1,1 0,2,0 1,0,0 1,1,0 1,2,1  |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      +                                  |
|      0,0,1 0,1,0 0,2,1 1,0,0 1,1,0 1,2,1                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,0 0,1,1 0,2,1 1,0,0 1,1,0 1,2,1                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      +                                  |
|      0,0,1 0,1,0 0,2,0 1,0,1 1,1,0 1,2,1                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     2a     a     a     a     a     a      -                                 |
|       0,0,0 0,1,1 0,2,0 1,0,1 1,1,0 1,2,1                                   |
|     ------------------------------------------------------------------------|
|                                             2           2                   |
|     a     a     a     a     a     a      + a     a     a     a      -       |
|      0,0,0 0,1,0 0,2,1 1,0,1 1,1,0 1,2,1    0,0,1 0,2,0 1,1,0 1,2,1         |
|     ------------------------------------------------------------------------|
|                        2                                                    |
|     a     a     a     a     a      + 2a     a     a     a     a     a      -|
|      0,0,0 0,0,1 0,2,1 1,1,0 1,2,1     0,0,1 0,1,0 0,2,0 1,0,0 1,1,1 1,2,1  |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,0 0,1,1 0,2,0 1,0,0 1,1,1 1,2,1                                    |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a     a     a     a     a     a      -                                  |
|      0,0,0 0,1,0 0,2,1 1,0,0 1,1,1 1,2,1                                    |
|     ------------------------------------------------------------------------|
|                                             2                               |
|     a     a     a     a     a     a      + a     a     a     a     a      + |
|      0,0,0 0,0,1 0,2,0 1,1,0 1,1,1 1,2,1    0,0,0 0,2,1 1,1,0 1,1,1 1,2,1   |
|     ------------------------------------------------------------------------|
|                                                   2                         |
|     a     a     a     a     a     a      - a     a     a     a     a      + |
|      0,0,1 0,1,0 0,1,1 1,0,0 1,2,0 1,2,1    0,0,0 0,1,1 1,0,0 1,2,0 1,2,1   |
|     ------------------------------------------------------------------------|
|            2                                                                |
|     a     a     a     a     a      - a     a     a     a     a     a      - |
|      0,0,1 0,1,0 1,0,1 1,2,0 1,2,1    0,0,0 0,1,0 0,1,1 1,0,1 1,2,0 1,2,1   |
|     ------------------------------------------------------------------------|
|      2                                                                      |
|     a     a     a     a     a      + a     a     a     a     a     a      - |
|      0,0,1 0,1,0 1,1,0 1,2,0 1,2,1    0,0,0 0,0,1 0,1,1 1,1,0 1,2,0 1,2,1   |
|     ------------------------------------------------------------------------|
|                                             2                               |
|     a     a     a     a     a     a      + a     a     a     a     a      - |
|      0,0,0 0,0,1 0,1,0 1,1,1 1,2,0 1,2,1    0,0,0 0,1,1 1,1,1 1,2,0 1,2,1   |
|     ------------------------------------------------------------------------|
|            2           2                                2                   |
|     a     a     a     a      + a     a     a     a     a      +             |
|      0,0,1 0,1,0 1,0,0 1,2,1    0,0,0 0,1,0 0,1,1 1,0,0 1,2,1               |
|     ------------------------------------------------------------------------|
|                              2        2                 2                   |
|     a     a     a     a     a      - a     a     a     a                    |
|      0,0,0 0,0,1 0,1,0 1,1,0 1,2,1    0,0,0 0,1,1 1,1,0 1,2,1               |
|                                                                             |
|o2 : ZZ[a     ..a     ]                                                      |
|         0,0,0   1,2,1                                                       |
+-----------------------------------------------------------------------------+
|i3 : A = exponentsMatrix f                                                   |
|                                                                             |
|o3 = | 0 0 0 0 0 0 1 1 1 1 1 1 |                                             |
|     | 1 1 1 1 1 1 0 0 0 0 0 0 |                                             |
|     | 0 0 0 0 1 1 0 0 0 0 1 1 |                                             |
|     | 0 0 1 1 0 0 0 0 1 1 0 0 |                                             |
|     | 1 1 0 0 0 0 1 1 0 0 0 0 |                                             |
|     | 0 1 0 1 0 1 0 1 0 1 0 1 |                                             |
|     | 1 0 1 0 1 0 1 0 1 0 1 0 |                                             |
|                                                                             |
|              7        12                                                    |
|o3 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i4 : Disc = sparseDiscriminant A                                             |
|                                                                             |
|o4 = Disc                                                                    |
|                                                                             |
|o4 : SparseDiscriminant (sparse discriminant associated to | 0 0 0 0 0 0 1 1 |
|                                                           | 1 1 1 1 1 1 0 0 |
|                                                           | 0 0 0 0 1 1 0 0 |
|                                                           | 0 0 1 1 0 0 0 0 |
|                                                           | 1 1 0 0 0 0 1 1 |
|                                                           | 0 1 0 1 0 1 0 1 |
|                                                           | 1 0 1 0 1 0 1 0 |
|-----------------------------------------------------------------------------|
|1 1 1 1 |)                                                                   |
|0 0 0 0 |                                                                    |
|0 0 1 1 |                                                                    |
|1 1 0 0 |                                                                    |
|0 0 0 0 |                                                                    |
|0 1 0 1 |                                                                    |
|1 0 1 0 |                                                                    |
+-----------------------------------------------------------------------------+
|i5 : assert(Disc f == sparseDiscriminant f)                                  |
+-----------------------------------------------------------------------------+

See also
========

  * sparseResultant -- sparse resultant (A-resultant)
  * denseDiscriminant -- dense discriminant
    (classical discriminant)
  * discriminant (Resultants) -- resultant of the partial
    derivatives
  * genericMultihomogeneousPolynomial,
    -- generic multi-homogeneous polynomial
  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix

Ways to use sparseDiscriminant :
================================

  * "sparseDiscriminant(Matrix)"
  * "sparseDiscriminant(RingElement)"

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

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

SparseDiscriminant Thing -- evaluate a sparse discriminant
**********************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        D(F)
  * Inputs:
      * D, an instance of the type SparseDiscriminant,
        associated to an integral matrix $A$ with $n$
        rows.
      * a thing (Macaulay2Doc), a Laurent polynomial $F =
        \sum_{\omega\in \{columns\ of\ A\}} a_{\omega} x^{\omega}$ in $n$
        variables $x=(x_1,\ldots,x_n)$.
  * Outputs:
      * a ring element (Macaulay2Doc), the $A$-discriminant
        of $F$.

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

+---------------------------------------------------------------------------+
|i1 : D = denseDiscriminant(2,2);                                           |
|                                                                           |
|o1 : SparseDiscriminant (sparse discriminant associated to | 0 0 0 1 1 2 |)|
|                                                           | 0 1 2 0 1 0 | |
+---------------------------------------------------------------------------+
|i2 : QQ[a..f][x,y]; F = a*x^2+b*x*y+c*y^2+d*x+e*y+f                        |
|                                                                           |
|        2              2                                                   |
|o3 = a*x  + b*x*y + c*y  + d*x + e*y + f                                   |
|                                                                           |
|o3 : QQ[a..f][x..y]                                                        |
+---------------------------------------------------------------------------+
|i4 : D(F)                                                                  |
|                                                                           |
|        2              2    2                                              |
|o4 = c*d  - b*d*e + a*e  + b f - 4a*c*f                                    |
|                                                                           |
|o4 : QQ[a..f]                                                              |
+---------------------------------------------------------------------------+

See also
========

  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)

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

  * SparseDiscriminant Thing -- evaluate a
    sparse discriminant

SparseResultant -- the class of all sparse resultants
*****************************************************

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

An object of this class is created by the method sparseResultant,
when the input is given by $n+1$ integral matrices
$A_0,\ldots,A_n$ with $n$ rows. Such an object behaves like a function that to
$n+1$ Laurent polynomials $f_0,\ldots,f_n$ in $n$ variables
$x=(x_1,\ldots,x_n)$, with $f_i = \sum_{\omega\in \{columns\ of\ A_i\}}
a_{i,\omega} x^{\omega}$, associates their sparse resultant
$Res_{A_0,\ldots,A_n}(f_0,\ldots,f_n)$, which is a polynomial in the
coefficients $a_{i,\omega}$. An error is thrown if the polynomials $f_i$ do not
have the correct form.

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

  * sparseResultant -- sparse resultant (A-resultant)

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

  * char(SparseResultant) -- get the
    characteristic
  * exponents(SparseResultant) -- get
    the matrices of exponents
  * SparseResultant Thing -- evaluate a sparse
    resultant

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

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

sparseResultant -- sparse resultant (A-resultant)
*************************************************

Synopsis
========

  * Usage:
        sparseResultant A
  * Inputs:
      * A, a sequence (Macaulay2Doc), or a list (Macaulay2Doc),
        of $n+1$ matrices $A_0,\ldots,A_n$ over
        $\mathbb{Z}$ and with $n$ rows to represent the exponent vectors of
        Laurent polynomials $f_0,\ldots,f_n$ in $n$ variables, $f_i =
        \sum_{\omega\in A_i} a_{i,\omega} x^{\omega}$. In the unmixed case,
        that is when $A_0=\cdots=A_n$, it is enough to pass just one of the
        matrices. Moreover, if one wants to perform computations only in
        characteristic $p>0$, then it is recommended to use the option
        CoefficientRing=>ZZ/p.
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => ..., default value ZZ
      * Unmixed => ..., default value null
  * Outputs:
      * an instance of the type SparseResultant, the
        universal sparse resultant associated to $A$, that is, a function that
        to a sequence (Macaulay2Doc), (or a list (Macaulay2Doc),
        or a row matrix (Macaulay2Doc)) of
        $n+1$ Laurent polynomials $f_0,\ldots,f_n$ in $n$ variables over a
        coefficient ring $K$, involving only monomials from $A$, associates the
        sparse resultant of the polynomials $f_0,\ldots,f_n$, which is an
        element of $K$.

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

Alternatively, one can apply the method directly to the list of Laurent
polynomials $f_0,\ldots,f_n$. In this case, the matrices $A_0,\ldots,A_n$ are
automatically determined by exponentsMatrix. If you
want require that $A_0=\cdots=A_n$, then use the option Unmixed=>true (this
could be faster). Below we consider some examples.

In the first example, we calculate the sparse (mixed) resultant associated to
the three sets of monomials $(1,x y,x^2 y,x),(y,x^2 y^2,x^2 y,x),(1,y,x y,x)$.
Then we evaluate it at the three polynomials $f = c_{(1,1)}+c_{(1,2)} x
y+c_{(1,3)} x^2 y+c_{(1,4)} x, g = c_{(2,1)} y+c_{(2,2)} x^2 y^2+c_{(2,3)} x^2
y+c_{(2,4)} x, h = c_{(3,1)}+c_{(3,2)} y+c_{(3,3)} x y+c_{(3,4)} x$.

+-----------------------------------------------------------------------------+
|i1 : time Res = sparseResultant(matrix{{0,1,1,2},{0,0,1,1}},matrix{{0,1,2,2  |
|     -- used 1.32479 seconds                                                 |
|                                                                             |
|o1 = Res                                                                     |
|                                                                             |
|o1 : SparseResultant (sparse mixed resultant associated to {| 0 1 1 2 |, |   |
|                                                            | 0 0 1 1 |  |   |
|-----------------------------------------------------------------------------|
|},{1,0,1,2}},matrix{{0,0,1,1},{0,1,0,1}})                                    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|0 1 2 2 |, | 0 0 1 1 |})                                                     |
|1 0 1 2 |  | 0 1 0 1 |                                                       |
+-----------------------------------------------------------------------------+
|i2 : QQ[c_(1,1)..c_(3,4)][x,y];                                              |
+-----------------------------------------------------------------------------+
|i3 : (f,g,h) = (c_(1,1)+c_(1,2)*x*y+c_(1,3)*x^2*y+c_(1,4)*x, c_(2,1)*y+c_(2,2|
|                                                                             |
|           2                                 2 2        2                    |
|o3 = (c   x y + c   x*y + c   x + c   , c   x y  + c   x y + c   x + c   y,  |
|       1,3       1,2       1,4     1,1   2,2        2,3       2,4     2,1    |
|     ------------------------------------------------------------------------|
|     c   x*y + c   x + c   y + c   )                                         |
|      3,3       3,4     3,2     3,1                                          |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|)*x^2*y^2+c_(2,3)*x^2*y+c_(2,4)*x, c_(3,1)+c_(3,2)*y+c_(3,3)*x*y+c_(3,4)*x)  |
+-----------------------------------------------------------------------------+
|i4 : time Res(f,g,h)                                                         |
|     -- used 0.0248587 seconds                                               |
|                                                                             |
|        2                       4      2   2               4                 |
|o4 = - c   c   c   c   c   c   c    + c   c   c   c   c   c    +             |
|        1,2 1,3 1,4 2,1 2,2 2,3 3,1    1,2 1,3 2,1 2,2 2,4 3,1               |
|     ------------------------------------------------------------------------|
|      3       2       3               2                   3                  |
|     c   c   c   c   c   c    - 2c   c   c   c   c   c   c   c    +          |
|      1,3 1,4 2,1 2,3 3,1 3,2     1,1 1,3 1,4 2,1 2,2 2,3 3,1 3,2            |
|     ------------------------------------------------------------------------|
|               2               3          2           2       3              |
|     2c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    +      |
|       1,2 1,3 1,4 2,1 2,2 2,3 3,1 3,2    1,1 1,3 1,4 2,2 2,3 3,1 3,2        |
|     ------------------------------------------------------------------------|
|      2               2   3          4   2       3                           |
|     c   c   c   c   c   c   c    - c   c   c   c   c    +                   |
|      1,2 1,3 1,4 2,1 2,3 3,1 3,2    1,3 2,1 2,4 3,1 3,2                     |
|     ------------------------------------------------------------------------|
|           3               3               2                   3             |
|     2c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c   c    -     |
|       1,1 1,3 2,1 2,2 2,4 3,1 3,2     1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,2       |
|     ------------------------------------------------------------------------|
|      2   2   2       3          2   2               3                       |
|     c   c   c   c   c   c    - c   c   c   c   c   c   c    -               |
|      1,1 1,3 2,2 2,4 3,1 3,2    1,2 1,3 2,1 2,3 2,4 3,1 3,2                 |
|     ------------------------------------------------------------------------|
|          3               2   2           2           2   2   2              |
|     c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -          |
|      1,3 1,4 2,1 2,2 2,3 3,1 3,2     1,1 1,3 1,4 2,1 2,3 3,1 3,2            |
|     ------------------------------------------------------------------------|
|               2       2   2   2       2               2   2   2             |
|     2c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +         |
|       1,2 1,3 1,4 2,1 2,3 3,1 3,2     1,1 1,3 1,4 2,2 2,3 3,1 3,2           |
|     ------------------------------------------------------------------------|
|      2   2               2   2           3               2   2              |
|     c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +          |
|      1,3 1,4 2,1 2,2 2,4 3,1 3,2     1,1 1,3 2,1 2,3 2,4 3,1 3,2            |
|     ------------------------------------------------------------------------|
|           2                   2   2       2   2               2   2         |
|     3c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    +     |
|       1,2 1,3 1,4 2,1 2,3 2,4 3,1 3,2     1,1 1,3 2,2 2,3 2,4 3,1 3,2       |
|     ------------------------------------------------------------------------|
|                                  2   2          3       2   2   2           |
|     c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c    -       |
|      1,1 1,2 1,3 1,4 2,2 2,3 2,4 3,1 3,2    1,2 1,3 2,1 2,4 3,1 3,2         |
|     ------------------------------------------------------------------------|
|              2       2   2   2          3       2       3                   |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c    +               |
|      1,1 1,2 1,3 2,2 2,4 3,1 3,2    1,3 1,4 2,1 2,3 3,1 3,2                 |
|     ------------------------------------------------------------------------|
|      2           3       3       2   2                   3                  |
|     c   c   c   c   c   c    - 2c   c   c   c   c   c   c    -              |
|      1,1 1,3 1,4 2,3 3,1 3,2     1,3 1,4 2,1 2,3 2,4 3,1 3,2                |
|     ------------------------------------------------------------------------|
|              2                   3      2   2   2           3               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c    -           |
|      1,1 1,3 1,4 2,2 2,3 2,4 3,1 3,2    1,1 1,3 2,3 2,4 3,1 3,2             |
|     ------------------------------------------------------------------------|
|                      2           3      3           2       3               |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c    +           |
|      1,1 1,2 1,3 1,4 2,3 2,4 3,1 3,2    1,3 1,4 2,1 2,4 3,1 3,2             |
|     ------------------------------------------------------------------------|
|          2           2       3              2       2       3               |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c   c    +           |
|      1,1 1,3 1,4 2,2 2,4 3,1 3,2    1,1 1,2 1,3 2,3 2,4 3,1 3,2             |
|     ------------------------------------------------------------------------|
|              2   2       4           2           2   4          3   3   4   |
|     c   c   c   c   c   c    - 2c   c   c   c   c   c    + c   c   c   c    |
|      1,1 1,3 1,4 2,3 2,4 3,2     1,1 1,3 1,4 2,3 2,4 3,2    1,1 1,3 2,4 3,2 |
|     ------------------------------------------------------------------------|
|            2       2       3                                      3         |
|     - c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c   c    + |
|        1,2 1,3 1,4 2,1 2,3 3,1 3,3    1,1 1,2 1,3 1,4 2,1 2,2 2,3 3,1 3,3   |
|     ------------------------------------------------------------------------|
|      2   2               3          3           2   3                       |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c    +               |
|      1,2 1,4 2,1 2,2 2,3 3,1 3,3    1,2 1,4 2,1 2,3 3,1 3,3                 |
|     ------------------------------------------------------------------------|
|          3   2       3                  2               3                   |
|     c   c   c   c   c   c    - c   c   c   c   c   c   c   c    -           |
|      1,2 1,3 2,1 2,4 3,1 3,3    1,1 1,2 1,3 2,1 2,2 2,4 3,1 3,3             |
|     ------------------------------------------------------------------------|
|      2                       3          3                   3               |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -       |
|      1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,3    1,2 1,3 2,1 2,3 2,4 3,1 3,3         |
|     ------------------------------------------------------------------------|
|       2   2   2       2                       2               2             |
|     2c   c   c   c   c   c   c    + 3c   c   c   c   c   c   c   c   c    - |
|       1,3 1,4 2,1 2,3 3,1 3,2 3,3     1,1 1,3 1,4 2,1 2,2 2,3 3,1 3,2 3,3   |
|     ------------------------------------------------------------------------|
|           3               2              2   2   2       2                  |
|     2c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -      |
|       1,2 1,4 2,1 2,2 2,3 3,1 3,2 3,3    1,1 1,4 2,2 2,3 3,1 3,2 3,3        |
|     ------------------------------------------------------------------------|
|                           2   2               2   2       2   2             |
|     4c   c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    + |
|       1,1 1,2 1,3 1,4 2,1 2,3 3,1 3,2 3,3     1,2 1,4 2,1 2,3 3,1 3,2 3,3   |
|     ------------------------------------------------------------------------|
|      2               2   2               3       2       2                  |
|     c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -      |
|      1,1 1,2 1,4 2,2 2,3 3,1 3,2 3,3     1,3 1,4 2,1 2,4 3,1 3,2 3,3        |
|     ------------------------------------------------------------------------|
|           2                   2                                             |
|     3c   c   c   c   c   c   c   c   c    +                                 |
|       1,1 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,3                                   |
|     ------------------------------------------------------------------------|
|               2               2              2           2       2          |
|     2c   c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c   |
|       1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,3    1,1 1,3 1,4 2,2 2,4 3,1 3,2 3,3|
|     ------------------------------------------------------------------------|
|                 2               2                                           |
|     + 4c   c   c   c   c   c   c   c   c    -                               |
|         1,1 1,2 1,3 2,1 2,3 2,4 3,1 3,2 3,3                                 |
|     ------------------------------------------------------------------------|
|       2                       2                                             |
|     4c   c   c   c   c   c   c   c   c    -                                 |
|       1,2 1,3 1,4 2,1 2,3 2,4 3,1 3,2 3,3                                   |
|     ------------------------------------------------------------------------|
|      2                       2               2   2       2   2              |
|     c   c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    +  |
|      1,1 1,2 1,3 2,2 2,3 2,4 3,1 3,2 3,3     1,2 1,3 2,1 2,4 3,1 3,2 3,3    |
|     ------------------------------------------------------------------------|
|      4                   2              3       2       2                   |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +           |
|      1,4 2,1 2,2 2,3 3,1 3,2 3,3    1,2 1,4 2,1 2,3 3,1 3,2 3,3             |
|     ------------------------------------------------------------------------|
|      2   2       2       2          2           3       2                   |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -           |
|      1,1 1,4 2,2 2,3 3,1 3,2 3,3    1,1 1,2 1,4 2,3 3,1 3,2 3,3             |
|     ------------------------------------------------------------------------|
|          3                   2               2                       2      |
|     c   c   c   c   c   c   c   c    - 3c   c   c   c   c   c   c   c   c   |
|      1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,3     1,1 1,3 1,4 2,1 2,3 2,4 3,1 3,2 3,3|
|     ------------------------------------------------------------------------|
|                 2                   2                                       |
|     + 3c   c   c   c   c   c   c   c   c    +                               |
|         1,2 1,3 1,4 2,1 2,3 2,4 3,1 3,2 3,3                                 |
|     ------------------------------------------------------------------------|
|       2                           2                                         |
|     2c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,3 1,4 2,2 2,3 2,4 3,1 3,2 3,3                                   |
|     ------------------------------------------------------------------------|
|              2                   2          2           2           2       |
|     c   c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    |
|      1,1 1,2 1,4 2,2 2,3 2,4 3,1 3,2 3,3    1,1 1,2 1,3 2,3 2,4 3,1 3,2 3,3 |
|     ------------------------------------------------------------------------|
|            2       2           2               3       2       2            |
|     + c   c   c   c   c   c   c   c    + 3c   c   c   c   c   c   c    -    |
|        1,1 1,2 1,4 2,3 2,4 3,1 3,2 3,3     1,1 1,3 2,1 2,4 3,1 3,2 3,3      |
|     ------------------------------------------------------------------------|
|           2           2       2           2   2       2       2             |
|     2c   c   c   c   c   c   c   c    - 3c   c   c   c   c   c   c    +     |
|       1,2 1,3 1,4 2,1 2,4 3,1 3,2 3,3     1,1 1,3 2,2 2,4 3,1 3,2 3,3       |
|     ------------------------------------------------------------------------|
|                          2       2              2           2       2       |
|     c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    |
|      1,1 1,2 1,3 1,4 2,2 2,4 3,1 3,2 3,3    1,1 1,2 1,3 2,3 2,4 3,1 3,2 3,3 |
|     ------------------------------------------------------------------------|
|            3               3          2           2       3                 |
|     + c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -         |
|        1,1 1,4 2,2 2,3 2,4 3,2 3,3    1,1 1,3 1,4 2,3 2,4 3,2 3,3           |
|     ------------------------------------------------------------------------|
|              2   2       3                  2       2   3                   |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +           |
|      1,1 1,2 1,4 2,3 2,4 3,2 3,3    1,1 1,3 1,4 2,2 2,4 3,2 3,3             |
|     ------------------------------------------------------------------------|
|      2   2       2   3                               2   3                  |
|     c   c   c   c   c   c    + 3c   c   c   c   c   c   c   c    -          |
|      1,1 1,3 2,3 2,4 3,2 3,3     1,1 1,2 1,3 1,4 2,3 2,4 3,2 3,3            |
|     ------------------------------------------------------------------------|
|               2   3   3                   2   2       2   2                 |
|     2c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -             |
|       1,1 1,2 1,3 2,4 3,2 3,3     1,2 1,3 1,4 2,1 2,3 3,1 3,3               |
|     ------------------------------------------------------------------------|
|              2               2   2           2           2   2   2          |
|     c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -      |
|      1,1 1,2 1,4 2,1 2,2 2,3 3,1 3,3     1,1 1,2 1,4 2,1 2,3 3,1 3,3        |
|     ------------------------------------------------------------------------|
|           2       2       2   2                                  2   2      |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c   c    -  |
|       1,2 1,3 1,4 2,1 2,4 3,1 3,3    1,1 1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,3    |
|     ------------------------------------------------------------------------|
|           2                   2   2      3                   2   2          |
|     2c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -      |
|       1,1 1,2 1,3 2,1 2,3 2,4 3,1 3,3    1,2 1,4 2,1 2,3 2,4 3,1 3,3        |
|     ------------------------------------------------------------------------|
|      3           2   2   2          3   2               2                   |
|     c   c   c   c   c   c    + c   c   c   c   c   c   c    -               |
|      1,2 1,3 2,1 2,4 3,1 3,3    1,3 1,4 2,1 2,3 3,1 3,2 3,3                 |
|     ------------------------------------------------------------------------|
|          3                       2      2               2           2       |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -   |
|      1,1 1,4 2,1 2,2 2,3 3,1 3,2 3,3    1,1 1,3 1,4 2,1 2,3 3,1 3,2 3,3     |
|     ------------------------------------------------------------------------|
|      3           2           2      2   2   2               2               |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +           |
|      1,1 1,4 2,2 2,3 3,1 3,2 3,3    1,3 1,4 2,1 2,4 3,1 3,2 3,3             |
|     ------------------------------------------------------------------------|
|              2                       2      2   2                       2   |
|     c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    |
|      1,1 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,3    1,1 1,3 2,1 2,3 2,4 3,1 3,2 3,3 |
|     ------------------------------------------------------------------------|
|                                             2                               |
|     + 5c   c   c   c   c   c   c   c   c   c    -                           |
|         1,1 1,2 1,3 1,4 2,1 2,3 2,4 3,1 3,2 3,3                             |
|     ------------------------------------------------------------------------|
|      2   2                       2      3                           2       |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -   |
|      1,2 1,4 2,1 2,3 2,4 3,1 3,2 3,3    1,1 1,3 2,2 2,3 2,4 3,1 3,2 3,3     |
|     ------------------------------------------------------------------------|
|      2                               2               2       2           2  |
|     c   c   c   c   c   c   c   c   c    - 5c   c   c   c   c   c   c   c   |
|      1,1 1,2 1,4 2,2 2,3 2,4 3,1 3,2 3,3     1,1 1,2 1,3 2,1 2,4 3,1 3,2 3,3|
|     ------------------------------------------------------------------------|
|        2               2           2      2               2           2     |
|     + c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    + |
|        1,2 1,3 1,4 2,1 2,4 3,1 3,2 3,3    1,1 1,2 1,3 2,2 2,4 3,1 3,2 3,3   |
|     ------------------------------------------------------------------------|
|              2               2   2       2   2               2   2          |
|     c   c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +      |
|      1,1 1,3 1,4 2,1 2,3 2,4 3,2 3,3     1,1 1,4 2,2 2,3 2,4 3,2 3,3        |
|     ------------------------------------------------------------------------|
|      2           2       2   2          2           2   2   2               |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +           |
|      1,1 1,2 1,4 2,3 2,4 3,2 3,3    1,1 1,3 1,4 2,1 2,4 3,2 3,3             |
|     ------------------------------------------------------------------------|
|       2               2   2   2      2               2   2   2              |
|     2c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -          |
|       1,1 1,3 1,4 2,2 2,4 3,2 3,3    1,1 1,2 1,3 2,3 2,4 3,2 3,3            |
|     ------------------------------------------------------------------------|
|          2           2   2   2          2       3   2   2                   |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c    -               |
|      1,1 1,2 1,4 2,3 2,4 3,2 3,3    1,1 1,2 1,3 2,4 3,2 3,3                 |
|     ------------------------------------------------------------------------|
|          3   2           3      2               2       3                   |
|     c   c   c   c   c   c    - c   c   c   c   c   c   c    +               |
|      1,2 1,4 2,1 2,3 3,1 3,3    1,1 1,2 1,4 2,1 2,3 3,1 3,3                 |
|     ------------------------------------------------------------------------|
|              2   2           3      2                           3           |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -       |
|      1,2 1,3 1,4 2,1 2,4 3,1 3,3    1,1 1,2 1,3 2,1 2,3 2,4 3,1 3,3         |
|     ------------------------------------------------------------------------|
|           2                       3           2           2       3         |
|     2c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -     |
|       1,1 1,2 1,4 2,1 2,3 2,4 3,1 3,3     1,1 1,2 1,3 2,1 2,4 3,1 3,3       |
|     ------------------------------------------------------------------------|
|      2                           3              2                   3       |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    +   |
|      1,1 1,3 1,4 2,1 2,3 2,4 3,2 3,3    1,1 1,2 1,4 2,1 2,3 2,4 3,2 3,3     |
|     ------------------------------------------------------------------------|
|      3                       3      2   2       2       3                   |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c    +               |
|      1,1 1,4 2,2 2,3 2,4 3,2 3,3    1,1 1,3 2,1 2,4 3,2 3,3                 |
|     ------------------------------------------------------------------------|
|                          2       3      3           2       3               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c    +           |
|      1,1 1,2 1,3 1,4 2,1 2,4 3,2 3,3    1,1 1,3 2,2 2,4 3,2 3,3             |
|     ------------------------------------------------------------------------|
|      2                       4      2               2   4                   |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c    -               |
|      1,1 1,2 1,4 2,1 2,3 2,4 3,3    1,1 1,2 1,3 2,1 2,4 3,3                 |
|     ------------------------------------------------------------------------|
|      2   2       2   3              2                   3                   |
|     c   c   c   c   c   c    + c   c   c   c   c   c   c   c    +           |
|      1,2 1,4 2,1 2,2 3,1 3,4    1,1 1,2 1,3 2,1 2,2 2,3 3,1 3,4             |
|     ------------------------------------------------------------------------|
|      3                   3           3                   3                  |
|     c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +          |
|      1,2 1,4 2,1 2,2 2,3 3,1 3,4     1,2 1,3 2,1 2,2 2,4 3,1 3,4            |
|     ------------------------------------------------------------------------|
|      2   2   2       2                       2       2   2                  |
|     c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c   c    +      |
|      1,3 1,4 2,1 2,2 3,1 3,2 3,4     1,1 1,3 1,4 2,1 2,2 3,1 3,2 3,4        |
|     ------------------------------------------------------------------------|
|           3       2   2              2   2   3   2                          |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c    -              |
|       1,2 1,4 2,1 2,2 3,1 3,2 3,4    1,1 1,4 2,2 3,1 3,2 3,4                |
|     ------------------------------------------------------------------------|
|          3   2       2               2   2               2                  |
|     c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c   c    -      |
|      1,1 1,3 2,1 2,3 3,1 3,2 3,4     1,1 1,3 2,1 2,2 2,3 3,1 3,2 3,4        |
|     ------------------------------------------------------------------------|
|                                  2                                          |
|     c   c   c   c   c   c   c   c   c   c    -                              |
|      1,1 1,2 1,3 1,4 2,1 2,2 2,3 3,1 3,2 3,4                                |
|     ------------------------------------------------------------------------|
|       2   2               2              3       2       2                  |
|     2c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -      |
|       1,2 1,4 2,1 2,2 2,3 3,1 3,2 3,4    1,1 1,3 2,2 2,3 3,1 3,2 3,4        |
|     ------------------------------------------------------------------------|
|      2           2       2                  2           2   2               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    +   |
|      1,1 1,2 1,4 2,2 2,3 3,1 3,2 3,4    1,1 1,2 1,3 2,1 2,3 3,1 3,2 3,4     |
|     ------------------------------------------------------------------------|
|          3   2       2                       2               2              |
|     c   c   c   c   c   c   c    - 3c   c   c   c   c   c   c   c   c    +  |
|      1,2 1,3 2,1 2,4 3,1 3,2 3,4     1,1 1,2 1,3 2,1 2,2 2,4 3,1 3,2 3,4    |
|     ------------------------------------------------------------------------|
|       2                       2                                             |
|     5c   c   c   c   c   c   c   c   c    +                                 |
|       1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,4                                   |
|     ------------------------------------------------------------------------|
|       2           2       2              3                   2              |
|     2c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -  |
|       1,1 1,2 1,3 2,2 2,4 3,1 3,2 3,4    1,2 1,3 2,1 2,3 2,4 3,1 3,2 3,4    |
|     ------------------------------------------------------------------------|
|      4       2       2           2   2   2           2                      |
|     c   c   c   c   c   c    + 2c   c   c   c   c   c   c    +              |
|      1,4 2,1 2,2 3,1 3,2 3,4     1,3 1,4 2,1 2,3 3,1 3,2 3,4                |
|     ------------------------------------------------------------------------|
|          3                   2          2   2   2           2               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -       |
|      1,2 1,4 2,1 2,2 2,3 3,1 3,2 3,4    1,1 1,4 2,2 2,3 3,1 3,2 3,4         |
|     ------------------------------------------------------------------------|
|       2   2       2       2                               2       2         |
|     2c   c   c   c   c   c   c    + 4c   c   c   c   c   c   c   c   c    + |
|       1,1 1,3 2,1 2,3 3,1 3,2 3,4     1,1 1,2 1,3 1,4 2,1 2,3 3,1 3,2 3,4   |
|     ------------------------------------------------------------------------|
|       3           2       2          2               2       2              |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -      |
|       1,1 1,3 2,2 2,3 3,1 3,2 3,4    1,1 1,2 1,4 2,2 2,3 3,1 3,2 3,4        |
|     ------------------------------------------------------------------------|
|       3       2           2               2                       2         |
|     2c   c   c   c   c   c   c    + 3c   c   c   c   c   c   c   c   c    - |
|       1,3 1,4 2,1 2,4 3,1 3,2 3,4     1,1 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,4   |
|     ------------------------------------------------------------------------|
|               2                   2          2           2           2      |
|     3c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c   |
|       1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,4    1,1 1,3 1,4 2,2 2,4 3,1 3,2 3,4|
|     ------------------------------------------------------------------------|
|                2   2           2                                            |
|     + c   c   c   c   c   c   c   c    -                                    |
|        1,1 1,2 1,4 2,2 2,4 3,1 3,2 3,4                                      |
|     ------------------------------------------------------------------------|
|              2                   2                                          |
|     c   c   c   c   c   c   c   c   c    -                                  |
|      1,1 1,2 1,3 2,1 2,3 2,4 3,1 3,2 3,4                                    |
|     ------------------------------------------------------------------------|
|      2                           2                                          |
|     c   c   c   c   c   c   c   c   c    -                                  |
|      1,2 1,3 1,4 2,1 2,3 2,4 3,1 3,2 3,4                                    |
|     ------------------------------------------------------------------------|
|       2                           2                                         |
|     4c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,2 1,3 2,2 2,3 2,4 3,1 3,2 3,4                                   |
|     ------------------------------------------------------------------------|
|          2                       2               2           2       2      |
|     c   c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c   c   |
|      1,1 1,2 1,4 2,2 2,3 2,4 3,1 3,2 3,4     1,1 1,2 1,3 2,2 2,4 3,1 3,2 3,4|
|     ------------------------------------------------------------------------|
|                2       2   3          3       3   3                         |
|     - c   c   c   c   c   c   c    - c   c   c   c   c    -                 |
|        1,1 1,3 1,4 2,1 2,3 3,2 3,4    1,1 1,3 2,3 3,2 3,4                   |
|     ------------------------------------------------------------------------|
|          3   2       3               2                   3                  |
|     c   c   c   c   c   c    + 4c   c   c   c   c   c   c   c    -          |
|      1,1 1,4 2,2 2,4 3,2 3,4     1,1 1,3 1,4 2,1 2,3 2,4 3,2 3,4            |
|     ------------------------------------------------------------------------|
|      2                       3                  2               3           |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    +   |
|      1,1 1,3 1,4 2,2 2,3 2,4 3,2 3,4    1,1 1,2 1,4 2,2 2,3 2,4 3,2 3,4     |
|     ------------------------------------------------------------------------|
|       2           2       3               3       2   3                     |
|     2c   c   c   c   c   c   c    - 3c   c   c   c   c   c    +             |
|       1,1 1,2 1,3 2,3 2,4 3,2 3,4     1,1 1,3 2,1 2,4 3,2 3,4               |
|     ------------------------------------------------------------------------|
|       2   2       2   3                               2   3                 |
|     3c   c   c   c   c   c    - 3c   c   c   c   c   c   c   c    -         |
|       1,1 1,3 2,2 2,4 3,2 3,4     1,1 1,2 1,3 1,4 2,2 2,4 3,2 3,4           |
|     ------------------------------------------------------------------------|
|          2           2   3                  2   2       2                   |
|     c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    +       |
|      1,1 1,2 1,3 2,3 2,4 3,2 3,4    1,2 1,3 1,4 2,1 2,2 3,1 3,3 3,4         |
|     ------------------------------------------------------------------------|
|              2       2   2                      2   2       2               |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -   |
|      1,1 1,2 1,4 2,1 2,2 3,1 3,3 3,4    1,1 1,2 1,3 2,1 2,3 3,1 3,3 3,4     |
|     ------------------------------------------------------------------------|
|      2                       2                                              |
|     c   c   c   c   c   c   c   c   c    -                                  |
|      1,1 1,2 1,3 2,1 2,2 2,3 3,1 3,3 3,4                                    |
|     ------------------------------------------------------------------------|
|           2                   2                  3       2   2              |
|     4c   c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -  |
|       1,1 1,2 1,4 2,1 2,2 2,3 3,1 3,3 3,4    1,1 1,2 2,1 2,3 3,1 3,3 3,4    |
|     ------------------------------------------------------------------------|
|      2   2   2       2                   2                   2              |
|     c   c   c   c   c   c   c    + 5c   c   c   c   c   c   c   c   c    -  |
|      1,2 1,3 2,1 2,4 3,1 3,3 3,4     1,1 1,2 1,3 2,1 2,2 2,4 3,1 3,3 3,4    |
|     ------------------------------------------------------------------------|
|      3                   2              4               2                   |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -       |
|      1,2 1,4 2,1 2,2 2,4 3,1 3,3 3,4    1,2 2,1 2,3 2,4 3,1 3,3 3,4         |
|     ------------------------------------------------------------------------|
|          3   2                              3       2                       |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    +   |
|      1,3 1,4 2,1 2,2 3,1 3,2 3,3 3,4    1,1 1,4 2,1 2,2 3,1 3,2 3,3 3,4     |
|     ------------------------------------------------------------------------|
|           2       2                                                         |
|     4c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,3 1,4 2,1 2,3 3,1 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|               2   2                                                         |
|     4c   c   c   c   c   c   c   c   c    -                                 |
|       1,2 1,3 1,4 2,1 2,3 3,1 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|       2                                                                     |
|     7c   c   c   c   c   c   c   c   c   c    +                             |
|       1,1 1,3 1,4 2,1 2,2 2,3 3,1 3,2 3,3 3,4                               |
|     ------------------------------------------------------------------------|
|               2                                                             |
|     5c   c   c   c   c   c   c   c   c   c    +                             |
|       1,1 1,2 1,4 2,1 2,2 2,3 3,1 3,2 3,3 3,4                               |
|     ------------------------------------------------------------------------|
|       3       2                                                             |
|     3c   c   c   c   c   c   c   c    +                                     |
|       1,1 1,4 2,2 2,3 3,1 3,2 3,3 3,4                                       |
|     ------------------------------------------------------------------------|
|       2               2                                                     |
|     4c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,2 1,3 2,1 2,3 3,1 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|           2           2                      3           2                  |
|     4c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c   |
|       1,1 1,2 1,4 2,1 2,3 3,1 3,2 3,3 3,4    1,1 1,2 2,2 2,3 3,1 3,2 3,3 3,4|
|     ------------------------------------------------------------------------|
|             3   2                                                           |
|     - 3c   c   c   c   c   c   c   c    +                                   |
|         1,1 1,3 2,1 2,4 3,1 3,2 3,3 3,4                                     |
|     ------------------------------------------------------------------------|
|           2       2                                                         |
|     3c   c   c   c   c   c   c   c   c    +                                 |
|       1,2 1,3 1,4 2,1 2,4 3,1 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|       2   2                                                                 |
|     6c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,3 2,1 2,2 2,4 3,1 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|                                                                             |
|     8c   c   c   c   c   c   c   c   c   c   c    +                         |
|       1,1 1,2 1,3 1,4 2,1 2,2 2,4 3,1 3,2 3,3 3,4                           |
|     ------------------------------------------------------------------------|
|      2   2                                   3       2                      |
|     c   c   c   c   c   c   c   c   c    - 3c   c   c   c   c   c   c   c   |
|      1,2 1,4 2,1 2,2 2,4 3,1 3,2 3,3 3,4     1,1 1,3 2,2 2,4 3,1 3,2 3,3 3,4|
|     ------------------------------------------------------------------------|
|        2           2                                                        |
|     + c   c   c   c   c   c   c   c   c    -                                |
|        1,1 1,2 1,4 2,2 2,4 3,1 3,2 3,3 3,4                                  |
|     ------------------------------------------------------------------------|
|          2                                                                  |
|     c   c   c   c   c   c   c   c   c   c    +                              |
|      1,1 1,2 1,3 2,1 2,3 2,4 3,1 3,2 3,3 3,4                                |
|     ------------------------------------------------------------------------|
|      3                                                                      |
|     c   c   c   c   c   c   c   c   c    +                                  |
|      1,2 1,4 2,1 2,3 2,4 3,1 3,2 3,3 3,4                                    |
|     ------------------------------------------------------------------------|
|      2   2                                      3               2           |
|     c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    |
|      1,1 1,2 2,2 2,3 2,4 3,1 3,2 3,3 3,4    1,1 1,4 2,1 2,2 2,3 3,2 3,3 3,4 |
|     ------------------------------------------------------------------------|
|                2       2   2              3           2   2                 |
|     + c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +     |
|        1,1 1,2 1,4 2,1 2,3 3,2 3,3 3,4    1,1 1,4 2,2 2,3 3,2 3,3 3,4       |
|     ------------------------------------------------------------------------|
|      3       3   2               2   2   2       2                          |
|     c   c   c   c   c   c    + 2c   c   c   c   c   c   c    +              |
|      1,1 1,2 2,3 3,2 3,3 3,4     1,1 1,4 2,2 2,4 3,2 3,3 3,4                |
|     ------------------------------------------------------------------------|
|      2   2               2                                                  |
|     c   c   c   c   c   c   c   c    -                                      |
|      1,1 1,3 2,1 2,3 2,4 3,2 3,3 3,4                                        |
|     ------------------------------------------------------------------------|
|                                   2                                         |
|     7c   c   c   c   c   c   c   c   c   c    -                             |
|       1,1 1,2 1,3 1,4 2,1 2,3 2,4 3,2 3,3 3,4                               |
|     ------------------------------------------------------------------------|
|      3                   2               2                       2          |
|     c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c   c   c   |
|      1,1 1,3 2,2 2,3 2,4 3,2 3,3 3,4     1,1 1,2 1,4 2,2 2,3 2,4 3,2 3,3 3,4|
|     ------------------------------------------------------------------------|
|         2   2   2       2                       2       2   2               |
|     - 2c   c   c   c   c   c   c    + 5c   c   c   c   c   c   c   c    -   |
|         1,1 1,2 2,3 2,4 3,2 3,3 3,4     1,1 1,2 1,3 2,1 2,4 3,2 3,3 3,4     |
|     ------------------------------------------------------------------------|
|      2               2   2                  2           2   2               |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    +   |
|      1,1 1,2 1,3 2,2 2,4 3,2 3,3 3,4    1,1 1,2 1,4 2,2 2,4 3,2 3,3 3,4     |
|     ------------------------------------------------------------------------|
|          3       2   2                  3   2           2                   |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -           |
|      1,1 1,2 2,3 2,4 3,2 3,3 3,4    1,2 1,4 2,1 2,2 3,1 3,3 3,4             |
|     ------------------------------------------------------------------------|
|                       2           2           2   2   2           2         |
|     4c   c   c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    + |
|       1,1 1,2 1,3 1,4 2,1 2,3 3,1 3,3 3,4     1,2 1,4 2,1 2,3 3,1 3,3 3,4   |
|     ------------------------------------------------------------------------|
|       2                           2           2   2       2       2         |
|     3c   c   c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    + |
|       1,1 1,2 1,4 2,1 2,2 2,3 3,1 3,3 3,4     1,1 1,2 2,1 2,3 3,1 3,3 3,4   |
|     ------------------------------------------------------------------------|
|               2   2           2          2           2           2          |
|     3c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    -  |
|       1,1 1,2 1,3 2,1 2,4 3,1 3,3 3,4    1,2 1,3 1,4 2,1 2,4 3,1 3,3 3,4    |
|     ------------------------------------------------------------------------|
|       2                           2                                         |
|     3c   c   c   c   c   c   c   c   c    +                                 |
|       1,1 1,2 1,3 2,1 2,2 2,4 3,1 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|           2                       2                                         |
|     2c   c   c   c   c   c   c   c   c    +                                 |
|       1,1 1,2 1,4 2,1 2,2 2,4 3,1 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|           3                   2                  2   2           2          |
|     2c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c    +  |
|       1,1 1,2 2,1 2,3 2,4 3,1 3,3 3,4    1,1 1,3 1,4 2,1 2,3 3,2 3,3 3,4    |
|     ------------------------------------------------------------------------|
|      2   2                   2          3           2       2               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +       |
|      1,1 1,4 2,1 2,2 2,3 3,2 3,3 3,4    1,1 1,3 2,1 2,3 3,2 3,3 3,4         |
|     ------------------------------------------------------------------------|
|      4       2       2              2       2           2                   |
|     c   c   c   c   c   c    + c   c   c   c   c   c   c   c    +           |
|      1,1 2,2 2,3 3,2 3,3 3,4    1,1 1,3 1,4 2,1 2,4 3,2 3,3 3,4             |
|     ------------------------------------------------------------------------|
|              2                   2          3       2           2           |
|     c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +   |
|      1,1 1,2 1,4 2,1 2,2 2,4 3,2 3,3 3,4    1,1 1,4 2,2 2,4 3,2 3,3 3,4     |
|     ------------------------------------------------------------------------|
|           2                       2          3                       2      |
|     3c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c   |
|       1,1 1,2 1,4 2,1 2,3 2,4 3,2 3,3 3,4    1,1 1,2 2,2 2,3 2,4 3,2 3,3 3,4|
|     ------------------------------------------------------------------------|
|             2           2       2                  2   2       3            |
|     - 2c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    +    |
|         1,1 1,2 1,3 2,1 2,4 3,2 3,3 3,4    1,1 1,2 1,4 2,1 2,3 3,3 3,4      |
|     ------------------------------------------------------------------------|
|      3           2   3                          2       3                   |
|     c   c   c   c   c   c    - c   c   c   c   c   c   c   c    -           |
|      1,1 1,2 2,1 2,3 3,3 3,4    1,1 1,2 1,3 1,4 2,1 2,4 3,3 3,4             |
|     ------------------------------------------------------------------------|
|      2                       3          2   2               3               |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    -       |
|      1,1 1,2 1,4 2,1 2,2 2,4 3,3 3,4    1,1 1,2 2,1 2,3 2,4 3,3 3,4         |
|     ------------------------------------------------------------------------|
|      2           2       2   2           2           2   2   2              |
|     c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    -          |
|      1,2 1,3 1,4 2,1 2,2 3,1 3,4     1,1 1,2 1,4 2,1 2,2 3,1 3,4            |
|     ------------------------------------------------------------------------|
|          3               2   2      4               2   2                   |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c    +               |
|      1,1 1,2 2,1 2,2 2,3 3,1 3,4    1,2 2,1 2,2 2,4 3,1 3,4                 |
|     ------------------------------------------------------------------------|
|      3       3           2           2       2               2              |
|     c   c   c   c   c   c    - 4c   c   c   c   c   c   c   c    +          |
|      1,3 1,4 2,1 3,1 3,2 3,4     1,1 1,3 1,4 2,1 2,2 3,1 3,2 3,4            |
|     ------------------------------------------------------------------------|
|               2   2               2       2               2           2     |
|     3c   c   c   c   c   c   c   c    + 5c   c   c   c   c   c   c   c    - |
|       1,2 1,3 1,4 2,1 2,2 3,1 3,2 3,4     1,1 1,3 1,4 2,1 2,2 3,1 3,2 3,4   |
|     ------------------------------------------------------------------------|
|               2       2           2       3       3           2             |
|     5c   c   c   c   c   c   c   c    - 2c   c   c   c   c   c    +         |
|       1,1 1,2 1,4 2,1 2,2 3,1 3,2 3,4     1,1 1,4 2,2 3,1 3,2 3,4           |
|     ------------------------------------------------------------------------|
|      2           2               2      2                               2   |
|     c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c   c    |
|      1,2 1,3 1,4 2,1 2,3 3,1 3,2 3,4    1,1 1,2 1,3 2,1 2,2 2,3 3,1 3,2 3,4 |
|     ------------------------------------------------------------------------|
|             2                           2      3       2               2    |
|     + 4c   c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -|
|         1,1 1,2 1,4 2,1 2,2 2,3 3,1 3,2 3,4    1,1 1,2 2,2 2,3 3,1 3,2 3,4  |
|     ------------------------------------------------------------------------|
|           2                           2      3                           2  |
|     3c   c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c   c   |
|       1,1 1,2 1,3 2,1 2,2 2,4 3,1 3,2 3,4    1,2 1,4 2,1 2,2 2,4 3,1 3,2 3,4|
|     ------------------------------------------------------------------------|
|        2   2   2               2          3       2   2   2                 |
|     - c   c   c   c   c   c   c    + c   c   c   c   c   c    -             |
|        1,1 1,2 2,2 2,4 3,1 3,2 3,4    1,1 1,4 2,1 2,2 3,2 3,4               |
|     ------------------------------------------------------------------------|
|           2       2       2   2      2                       2   2          |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -      |
|       1,1 1,3 1,4 2,1 2,3 3,2 3,4    1,1 1,3 1,4 2,1 2,2 2,3 3,2 3,4        |
|     ------------------------------------------------------------------------|
|              2               2   2      3       2       2   2               |
|     c   c   c   c   c   c   c   c    + c   c   c   c   c   c    -           |
|      1,1 1,2 1,4 2,1 2,2 2,3 3,2 3,4    1,1 1,4 2,2 2,3 3,2 3,4             |
|     ------------------------------------------------------------------------|
|       2               2   2   2      3           2   2   2                  |
|     2c   c   c   c   c   c   c    - c   c   c   c   c   c    +              |
|       1,1 1,2 1,3 2,1 2,3 3,2 3,4    1,1 1,2 2,2 2,3 3,2 3,4                |
|     ------------------------------------------------------------------------|
|           3   2       2   2       2   2               2   2                 |
|     3c   c   c   c   c   c    - 6c   c   c   c   c   c   c    +             |
|       1,1 1,3 2,1 2,4 3,2 3,4     1,1 1,3 2,1 2,2 2,4 3,2 3,4               |
|     ------------------------------------------------------------------------|
|                                   2   2       3       2       2   2         |
|     6c   c   c   c   c   c   c   c   c    + 3c   c   c   c   c   c    -     |
|       1,1 1,2 1,3 1,4 2,1 2,2 2,4 3,2 3,4     1,1 1,3 2,2 2,4 3,2 3,4       |
|     ------------------------------------------------------------------------|
|       2           2       2   2           2                   2   2         |
|     3c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c   c    +     |
|       1,1 1,2 1,4 2,2 2,4 3,2 3,4     1,1 1,2 1,3 2,1 2,3 2,4 3,2 3,4       |
|     ------------------------------------------------------------------------|
|       2   2               2   2          3       2   2   2                  |
|     2c   c   c   c   c   c   c    - c   c   c   c   c   c    -              |
|       1,1 1,2 2,2 2,3 2,4 3,2 3,4    1,1 1,2 2,2 2,4 3,2 3,4                |
|     ------------------------------------------------------------------------|
|          2       3           2                       2               2      |
|     c   c   c   c   c   c   c    + 3c   c   c   c   c   c   c   c   c    -  |
|      1,2 1,3 1,4 2,1 3,1 3,3 3,4     1,1 1,2 1,3 1,4 2,1 2,2 3,1 3,3 3,4    |
|     ------------------------------------------------------------------------|
|       2   2   2               2       2               2           2         |
|     2c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c   c    -     |
|       1,2 1,4 2,1 2,2 3,1 3,3 3,4     1,1 1,2 1,4 2,1 2,2 3,1 3,3 3,4       |
|     ------------------------------------------------------------------------|
|      3       2               2       2   2                       2          |
|     c   c   c   c   c   c   c    + 3c   c   c   c   c   c   c   c    -      |
|      1,2 1,4 2,1 2,3 3,1 3,3 3,4     1,1 1,2 2,1 2,2 2,3 3,1 3,3 3,4        |
|     ------------------------------------------------------------------------|
|           3                       2              2   2               2      |
|     2c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c   c    -  |
|       1,1 1,2 2,1 2,2 2,4 3,1 3,3 3,4    1,1 1,3 1,4 2,1 2,2 3,2 3,3 3,4    |
|     ------------------------------------------------------------------------|
|      2   2       2           2       2   2   2               2              |
|     c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +          |
|      1,1 1,4 2,1 2,2 3,2 3,3 3,4     1,1 1,3 2,1 2,3 3,2 3,3 3,4            |
|     ------------------------------------------------------------------------|
|                       2               2                                     |
|     4c   c   c   c   c   c   c   c   c    +                                 |
|       1,1 1,2 1,3 1,4 2,1 2,3 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|       3                           2                                         |
|     4c   c   c   c   c   c   c   c    -                                     |
|       1,1 1,3 2,1 2,2 2,3 3,2 3,3 3,4                                       |
|     ------------------------------------------------------------------------|
|       2                               2       4   2               2         |
|     3c   c   c   c   c   c   c   c   c    - 2c   c   c   c   c   c    +     |
|       1,1 1,2 1,4 2,1 2,2 2,3 3,2 3,3 3,4     1,1 2,2 2,3 3,2 3,3 3,4       |
|     ------------------------------------------------------------------------|
|       2   2       2           2               2   2               2         |
|     2c   c   c   c   c   c   c    - 4c   c   c   c   c   c   c   c    +     |
|       1,1 1,2 2,1 2,3 3,2 3,3 3,4     1,1 1,2 1,3 2,1 2,4 3,2 3,3 3,4       |
|     ------------------------------------------------------------------------|
|       2                               2                                     |
|     3c   c   c   c   c   c   c   c   c    -                                 |
|       1,1 1,2 1,3 2,1 2,2 2,4 3,2 3,3 3,4                                   |
|     ------------------------------------------------------------------------|
|           2                           2      3       2               2      |
|     3c   c   c   c   c   c   c   c   c    + c   c   c   c   c   c   c    -  |
|       1,1 1,2 1,4 2,1 2,2 2,4 3,2 3,3 3,4    1,1 1,2 2,2 2,4 3,2 3,3 3,4    |
|     ------------------------------------------------------------------------|
|           3                       2              2   2       2   2          |
|     2c   c   c   c   c   c   c   c    - c   c   c   c   c   c   c    +      |
|       1,1 1,2 2,1 2,3 2,4 3,2 3,3 3,4    1,1 1,2 1,4 2,1 2,2 3,3 3,4        |
|     ------------------------------------------------------------------------|
|       2           2       2   2           2       2       2   2             |
|     2c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    -         |
|       1,1 1,2 1,3 2,1 2,3 3,3 3,4     1,1 1,2 1,4 2,1 2,3 3,3 3,4           |
|     ------------------------------------------------------------------------|
|       3                   2   2          2       2       2   2              |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c   c    +          |
|       1,1 1,2 2,1 2,2 2,3 3,3 3,4    1,1 1,2 1,3 2,1 2,4 3,3 3,4            |
|     ------------------------------------------------------------------------|
|      2   2               2   2          2       2           3               |
|     c   c   c   c   c   c   c    + c   c   c   c   c   c   c    +           |
|      1,1 1,2 2,1 2,2 2,4 3,3 3,4    1,1 1,2 1,3 2,1 2,2 3,1 3,4             |
|     ------------------------------------------------------------------------|
|      3       2           3      2   2       2       3                       |
|     c   c   c   c   c   c    - c   c   c   c   c   c    -                   |
|      1,2 1,4 2,1 2,2 3,1 3,4    1,1 1,2 2,1 2,2 3,1 3,4                     |
|     ------------------------------------------------------------------------|
|          3   3       3       2   2   2           3                          |
|     c   c   c   c   c    + 3c   c   c   c   c   c    -                      |
|      1,1 1,3 2,1 3,2 3,4     1,1 1,3 2,1 2,2 3,2 3,4                        |
|     ------------------------------------------------------------------------|
|                       2           3       3           2       3             |
|     3c   c   c   c   c   c   c   c    - 3c   c   c   c   c   c    +         |
|       1,1 1,2 1,3 1,4 2,1 2,2 3,2 3,4     1,1 1,3 2,1 2,2 3,2 3,4           |
|     ------------------------------------------------------------------------|
|       2               2       3      4   3       3                          |
|     3c   c   c   c   c   c   c    + c   c   c   c    -                      |
|       1,1 1,2 1,4 2,1 2,2 3,2 3,4    1,1 2,2 3,2 3,4                        |
|     ------------------------------------------------------------------------|
|          2       2           3       2   2                   3              |
|     c   c   c   c   c   c   c    - 2c   c   c   c   c   c   c    +          |
|      1,1 1,2 1,3 2,1 2,3 3,2 3,4     1,1 1,2 2,1 2,2 2,3 3,2 3,4            |
|     ------------------------------------------------------------------------|
|           3                   3              2   3       3                  |
|     2c   c   c   c   c   c   c    + c   c   c   c   c   c    -              |
|       1,1 1,2 2,1 2,2 2,4 3,2 3,4    1,1 1,2 1,3 2,1 3,3 3,4                |
|     ------------------------------------------------------------------------|
|       2           2           3           2       2           3             |
|     2c   c   c   c   c   c   c    + 2c   c   c   c   c   c   c    +         |
|       1,1 1,2 1,3 2,1 2,2 3,3 3,4     1,1 1,2 1,4 2,1 2,2 3,3 3,4           |
|     ------------------------------------------------------------------------|
|      3           2       3          3   2           3                       |
|     c   c   c   c   c   c    + c   c   c   c   c   c    -                   |
|      1,1 1,2 2,1 2,2 3,3 3,4    1,1 1,2 2,1 2,3 3,3 3,4                     |
|     ------------------------------------------------------------------------|
|          3   2       4                                                      |
|     c   c   c   c   c                                                       |
|      1,1 1,2 2,1 2,2 3,4                                                    |
|                                                                             |
|o4 : QQ[c   ..c   ]                                                          |
|         1,1   3,4                                                           |
+-----------------------------------------------------------------------------+
|i5 : assert(Res(f,g,h) == sparseResultant(f,g,h))                            |
+-----------------------------------------------------------------------------+

In the second example, we calculate the sparse unmixed resultant associated to
the set of monomials $(1,x,y,xy)$. Then we evaluate it at the three polynomials
$f = a_0 + a_1 x + a_2 y + a_3 x y, g = b_0 + b_1 x + b_2 y + b_3 x y, h = c_0
+ c_1 x + c_2 y + c_3 x y$. Moreover, we perform all the computation over
$\mathbb{Z}/3331$.

+-----------------------------------------------------------------------------+
|i6 : time Res = sparseResultant(matrix{{0,0,1,1},{0,1,0,1}},CoefficientRing=>|
|     -- used 0.14243 seconds                                                 |
|                                                                             |
|o6 : SparseResultant (sparse unmixed resultant associated to | 0 0 1 1 | over|
|                                                             | 0 1 0 1 |     |
|-----------------------------------------------------------------------------|
|ZZ/3331);                                                                    |
|                                                                             |
|                                                                             |
| ZZ/3331)                                                                    |
+-----------------------------------------------------------------------------+
|i7 : ZZ/3331[a_0..a_3,b_0..b_3,c_0..c_3][x,y];                               |
+-----------------------------------------------------------------------------+
|i8 : (f,g,h) = (a_0 + a_1*x + a_2*y + a_3*x*y, b_0 + b_1*x + b_2*y + b_3*x*y,|
|                                                                             |
|o8 = (a x*y + a x + a y + a , b x*y + b x + b y + b , c x*y + c x + c y + c )|
|       3       1     2     0   3       1     2     0   3       1     2     0 |
|                                                                             |
|o8 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|c_0 + c_1*x + c_2*y + c_3*x*y)                                               |
+-----------------------------------------------------------------------------+
|i9 : time Res(f,g,h)                                                         |
|     -- used 0.00872765 seconds                                              |
|                                                                             |
|      2     2            2            2        2 2    2                      |
|o9 = a b b c  - a a b b c  - a a b b c  + a a b c  - a b b c c  -            |
|      3 1 2 0    2 3 1 3 0    1 3 2 3 0    1 2 3 0    3 0 2 0 1              |
|     ------------------------------------------------------------------------|
|                         2                       2                           |
|     a a b b c c  + a a b c c  + a a b b c c  + a b b c c  - a a b b c c  +  |
|      2 3 1 2 0 1    1 3 2 0 1    2 3 0 3 0 1    2 1 3 0 1    1 2 2 3 0 1    |
|     ------------------------------------------------------------------------|
|                         2                2        2 2    2     2            |
|     a a b b c c  - a a b c c  + a a b b c  - a a b c  - a b b c  +          |
|      0 3 2 3 0 1    0 2 3 0 1    2 3 0 2 1    0 3 2 1    2 0 3 1            |
|     ------------------------------------------------------------------------|
|              2    2                2                                        |
|     a a b b c  - a b b c c  + a a b c c  - a a b b c c  + a a b b c c  -    |
|      0 2 2 3 1    3 0 1 0 2    2 3 1 0 2    1 3 1 2 0 2    1 3 0 3 0 2      |
|     ------------------------------------------------------------------------|
|                                    2                2        2 2            |
|     a a b b c c  + a a b b c c  + a b b c c  - a a b c c  + a b c c  -      |
|      1 2 1 3 0 2    0 3 1 3 0 2    1 2 3 0 2    0 1 3 0 2    3 0 1 2        |
|     ------------------------------------------------------------------------|
|                                                                             |
|     a a b b c c  - a a b b c c  + 2a a b b c c  + 2a a b b c c  -           |
|      2 3 0 1 1 2    1 3 0 2 1 2     0 3 1 2 1 2     1 2 0 3 1 2             |
|     ------------------------------------------------------------------------|
|                                                    2 2                2     |
|     2a a b b c c  - a a b b c c  - a a b b c c  + a b c c  + a a b b c  -   |
|       0 3 0 3 1 2    0 2 1 3 1 2    0 1 2 3 1 2    0 3 1 2    1 3 0 1 2     |
|     ------------------------------------------------------------------------|
|          2 2    2     2            2                   2 2                  |
|     a a b c  - a b b c  + a a b b c  + a a b b c c  - a b c c  +            |
|      0 3 1 2    1 0 3 2    0 1 1 3 2    2 3 0 1 0 3    2 1 0 3              |
|     ------------------------------------------------------------------------|
|                                                     2 2                     |
|     a a b b c c  + 2a a b b c c  - 2a a b b c c  - a b c c  - 2a a b b c c  |
|      1 3 0 2 0 3     1 2 1 2 0 3     0 3 1 2 0 3    1 2 0 3     1 2 0 3 0 3 |
|     ------------------------------------------------------------------------|
|                                          2        2                         |
|     + a a b b c c  + a a b b c c  - a a b c c  + a b b c c  - a a b b c c  +|
|        0 2 1 3 0 3    0 1 2 3 0 3    2 3 0 1 3    2 0 1 1 3    1 2 0 2 1 3  |
|     ------------------------------------------------------------------------|
|                                        2                       2            |
|     a a b b c c  - a a b b c c  + a a b c c  + a a b b c c  - a b b c c  -  |
|      0 3 0 2 1 3    0 2 1 2 1 3    0 1 2 1 3    0 2 0 3 1 3    0 2 3 1 3    |
|     ------------------------------------------------------------------------|
|          2                                          2        2              |
|     a a b c c  - a a b b c c  + a a b b c c  + a a b c c  + a b b c c  -    |
|      1 3 0 2 3    1 2 0 1 2 3    0 3 0 1 2 3    0 2 1 2 3    1 0 2 2 3      |
|     ------------------------------------------------------------------------|
|                                    2                2 2            2        |
|     a a b b c c  + a a b b c c  - a b b c c  + a a b c  - a a b b c  -      |
|      0 1 1 2 2 3    0 1 0 3 2 3    0 1 3 2 3    1 2 0 3    0 2 0 1 3        |
|     ------------------------------------------------------------------------|
|              2    2     2                                                   |
|     a a b b c  + a b b c                                                    |
|      0 1 0 2 3    0 1 2 3                                                   |
|                                                                             |
|      ZZ                                                                     |
|o9 : ----[a ..c ]                                                            |
|     3331  0   3                                                             |
+-----------------------------------------------------------------------------+
|i10 : assert(Res(f,g,h) == sparseResultant(f,g,h))                           |
+-----------------------------------------------------------------------------+

In the third and last example, we compare the sparse mixed resultant and the
sparse unmixed resultant of three generic polynomials of degrees 1,2,2 in two
variables.

+-----------------------------------------------------------------------------+
|i11 : (f,g,h) = genericLaurentPolynomials(1,2,2)                             |
|                                                                             |
|                            2               2                        2       |
|o11 = (a x  + a x  + a , b x  + b x x  + b x  + b x  + b x  + b , c x  +     |
|        2 1    1 2    0   5 1    4 1 2    2 2    3 1    1 2    0   5 1       |
|      -----------------------------------------------------------------------|
|                  2                                                          |
|      c x x  + c x  + c x  + c x  + c )                                      |
|       4 1 2    2 2    3 1    1 2    0                                       |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i12 : time (MixedRes,UnmixedRes) =                                           |
|     -- used 2.71745 seconds                                                 |
|-----------------------------------------------------------------------------|
|(sparseResultant(f,g,h),sparseResultant(f,g,h,Unmixed=>true));               |
+-----------------------------------------------------------------------------+
|i13 : quotientRemainder(UnmixedRes,MixedRes)                                 |
|                                                                             |
|        2 2                   2    2                               2 2       |
|o13 = (b c  - b b c c  + b b c  + b c c  - 2b b c c  - b b c c  + b c , 0)   |
|        5 2    4 5 2 4    2 5 4    4 2 5     2 5 2 5    2 4 4 5    2 5       |
|                                                                             |
|o13 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i14 : assert((denseResultant(2,2,2))(f,g,h) == UnmixedRes and                |
|-----------------------------------------------------------------------------|
|(denseResultant(1,2,2))(f,g,h) == MixedRes)                                  |
+-----------------------------------------------------------------------------+

See also
========

  * sparseDiscriminant -- sparse discriminant
    (A-discriminant)
  * denseResultant -- dense resultant (classical
    resultant)
  * resultant (Resultants) -- multipolynomial resultant
  * genericLaurentPolynomials -- generic
    (Laurent) polynomials

Ways to use sparseResultant :
=============================

  * "sparseResultant(Thing)"

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

The object sparseResultant, is a method function with a single argument (Macaulay2Doc).

SparseResultant Thing -- evaluate a sparse resultant
****************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        R(f)
  * Inputs:
      * R, an instance of the type SparseResultant,
        associated to $n+1$ integral matrices $A_0,\ldots,A_n$ with $n$ rows.
      * a thing (Macaulay2Doc), $n+1$ Laurent polynomials $f =
        (f_0,\ldots,f_n)$ in $n$ variables $x=(x_1,\ldots,x_n)$, with $f_i =
        \sum_{\omega\in \{columns\ of\ A_i\}} a_{i,\omega} x^{\omega}$.
  * Outputs:
      * a ring element (Macaulay2Doc), the
        $(A_0,\ldots,A_n)$-resultant of $f_0,\ldots,f_n$.

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

+-----------------------------------------------------------------------------+
|i1 : R = denseResultant(2,3);                                                |
|                                                                             |
|o1 : SparseResultant (sparse mixed resultant associated to {| 0 1 2 |, | 0 1 |
|-----------------------------------------------------------------------------|
|2 3 |})                                                                      |
+-----------------------------------------------------------------------------+
|i2 : f = genericLaurentPolynomials(2,3)                                      |
|                                                                             |
|         2                 3      2                                          |
|o2 = (a x  + a x  + a , b x  + b x  + b x  + b )                             |
|       2 1    1 1    0   3 1    2 1    1 1    0                              |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : R(f)                                                                    |
|                                                                             |
|      3 2      2          2 2    2             2                     2   2   |
|o3 = a b  - a a b b  + a a b  + a a b b  - 2a a b b  - a a a b b  + a a b  - |
|      2 0    1 2 0 1    0 2 1    1 2 0 2     0 2 0 2    0 1 2 1 2    0 2 2   |
|     ------------------------------------------------------------------------|
|      3                        2         2          2          3 2           |
|     a b b  + 3a a a b b  + a a b b  - 2a a b b  - a a b b  + a b            |
|      1 0 3     0 1 2 0 3    0 1 1 3     0 2 1 3    0 1 2 3    0 3           |
|                                                                             |
|o3 : ZZ[a ..a , b ..b ]                                                      |
|         0   2   0   3                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * sparseResultant -- sparse resultant (A-resultant)

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

  * SparseResultant Thing -- evaluate a sparse
    resultant

sylvesterMatrix -- Sylvester-type matrix for the hyperdeterminant of a matrix of boundary shape
***********************************************************************************************

Synopsis
========

  * Usage:
        sylvesterMatrix M
  * Inputs:
      * M, a multidimensional matrix, an
        $n$-dimensional matrix of boundary shape $(k_1+1)\times\cdots\times
        (k_n+1)$ (that is, $2 max\{k_1,\ldots,k_n\} = k_1+\ldots+k_n$).
  * Outputs:
      * a matrix (Macaulay2Doc), a particular square matrix whose
        determinant is $det(M)$ (up to sign), introduced by Gelfand, Kapranov,
        and Zelevinsky.

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

This is an implementation of Theorem 3.3, Chapter 14, in Discriminants,
Resultants, and Multidimensional Determinants (see
http://link.springer.com/book/10.1007%2F978-0-8176-4771-1 ).

+-----------------------------------------------------------------------------+
|i1 : M = randomMultidimensionalMatrix {4,2,3}                                |
|                                                                             |
|o1 = {{{8, 1, 3}, {7, 8, 3}}, {{3, 7, 8}, {8, 5, 7}}, {{8, 5, 2}, {3, 6, 3}},|
|     ------------------------------------------------------------------------|
|     {{6, 8, 6}, {9, 3, 7}}}                                                 |
|                                                                             |
|o1 : 3-dimensional matrix of shape 4 x 2 x 3 over ZZ                         |
+-----------------------------------------------------------------------------+
|i2 : S = sylvesterMatrix M                                                   |
|                                                                             |
|o2 = | 8 1 3 0 0 0 7 8 3 0 0 0 |                                             |
|     | 0 8 0 1 3 0 0 7 0 8 3 0 |                                             |
|     | 0 0 8 0 1 3 0 0 7 0 8 3 |                                             |
|     | 3 7 8 0 0 0 8 5 7 0 0 0 |                                             |
|     | 0 3 0 7 8 0 0 8 0 5 7 0 |                                             |
|     | 0 0 3 0 7 8 0 0 8 0 5 7 |                                             |
|     | 8 5 2 0 0 0 3 6 3 0 0 0 |                                             |
|     | 0 8 0 5 2 0 0 3 0 6 3 0 |                                             |
|     | 0 0 8 0 5 2 0 0 3 0 6 3 |                                             |
|     | 6 8 6 0 0 0 9 3 7 0 0 0 |                                             |
|     | 0 6 0 8 6 0 0 9 0 3 7 0 |                                             |
|     | 0 0 6 0 8 6 0 0 9 0 3 7 |                                             |
|                                                                             |
|              12        12                                                   |
|o2 : Matrix ZZ   <--- ZZ                                                     |
+-----------------------------------------------------------------------------+
|i3 : det M                                                                   |
|                                                                             |
|o3 = 910015877                                                               |
+-----------------------------------------------------------------------------+
|i4 : det S                                                                   |
|                                                                             |
|o4 = 910015877                                                               |
+-----------------------------------------------------------------------------+
|i5 : assert(oo == ooo or oo == -ooo)                                         |
+-----------------------------------------------------------------------------+

See also
========

  * determinant(MultidimensionalMatrix)
    -- hyperdeterminant of a
    multidimensional matrix

Ways to use sylvesterMatrix :
=============================

  * "sylvesterMatrix(MultidimensionalMatrix)"

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

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