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

Kronecker -- Kronecker and rational normal forms
************************************************

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

This package provides methods for computing the Kronecker and rational normal
forms of a matrix.

Author
======

  * Edward Carter <edward.carter@gmail.com>

Version
=======

This documentation describes version 0.3.3 of Kronecker.

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

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

Exports
=======

  * Functions and commands
      * decomposeGradedModule -- decompose a
        graded module over a ring of graded module maps
      * decomposeModule -- decompose a module into a
        direct sum of simple modules
      * doubleDualMap (missing documentation)
      * kroneckerIndices -- data which classify a
        matrix pencil up to strict equivalence
      * kroneckerNormalForm -- Kronecker normal
        form of a matrix of linear forms
      * rationalNormalForm -- rational normal form
        of a matrix
  * Methods
      * "decomposeGradedModule(GradedModuleMap,GradedModuleMap)" -- see
        decomposeGradedModule, -- decompose a graded
        module over a ring of graded module maps
      * "decomposeModule(Module)" -- see decomposeModule,
        -- decompose a module into a direct sum of simple
        modules
      * doubleDualMap(Module,Module) (missing documentation)
      * "kroneckerIndices(Matrix,RingElement,RingElement)" -- see
        kroneckerIndices, -- data which classify a matrix
        pencil up to strict equivalence
      * kroneckerIndices(Matrix,Matrix)
        -- data classifying the normal
        form of a pair of matrices
      * "kroneckerNormalForm(Matrix)" -- see kroneckerNormalForm,
        -- Kronecker normal form of a matrix of linear
        forms
      * "kroneckerNormalForm(Matrix,RingElement,RingElement)" -- see
        kroneckerNormalForm, -- Kronecker normal form of a
        matrix of linear forms
      * kroneckerNormalForm(Matrix,Matrix)
        -- normal form of a pair of
        matrices of scalars
      * "rationalNormalForm(Matrix)" -- see rationalNormalForm,
        -- rational normal form of a matrix

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

The object Kronecker, is a package (Macaulay2Doc).

decomposeGradedModule -- decompose a graded module over a ring of graded module maps
************************************************************************************

Synopsis
========

  * Usage:
        (x',y',f) = decomposeGradedModule(x,y)
  * Inputs:
      * x, a graded module map (Macaulay2Doc), a graded
        module map of degree 1
      * y, a graded module map (Macaulay2Doc), a graded
        module map of degree 1
  * Outputs:
      * x', a graded module map (Macaulay2Doc),
      * y', a graded module map (Macaulay2Doc),
      * f, a graded module map (Macaulay2Doc), an
        isomorphism

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

Given maps x and y of degree 1 from a graded module M over a field k to M, we
can think of M as a module over k[x,y].  If x^2=0, y^2=0, and x*y+y*x=0, we can
decompose M into a direct sum of simple modules.

Ways to use decomposeGradedModule:
==================================

  * "decomposeGradedModule(GradedModuleMap,GradedModuleMap)"

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

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

decomposeModule -- decompose a module into a direct sum of simple modules
*************************************************************************

Synopsis
========

  * Usage:
        (N,f) = decomposeModule M
  * Inputs:
      * M, a module (Macaulay2Doc), a module over a ring
        k[x,y]/(x^2,y^2)
  * Outputs:
      * N, a module (Macaulay2Doc), a module, isomorphic to M
        which is a direct sum of simple modules
      * f, a matrix (Macaulay2Doc), an isomorphism from N to M

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

This function decomposes a module into a direct sum of simple modules, given
some fairly strong assumptions on the ring which acts on the ring which acts on
the module.  This ring must only have two variables, and the square of each of
those variables must kill the module.
+-----------------------------------------------------------------------------+
|i1 : Q = ZZ/101[x,y]                                                         |
|                                                                             |
|o1 = Q                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : R = Q/(x^2,y^2)                                                         |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i3 : M = coker random(R^5, R^8 ** R^{-1})                                    |
|                                                                             |
|o3 = cokernel | 24x-36y  -29x-24y -18x-13y 45x-34y  39x+43y  40x+11y 2x+29y  |
|              | -30x-29y -38x-16y -43x-15y -48x-47y -17x-11y 46x-28y -47x+15y|
|              | 19x+19y  39x+21y  -28x-47y 47x+19y  48x+36y  x-3y    -37x-13y|
|              | -10x-29y 34x+19y  38x+2y   -16x+7y  35x+11y  22x-47y -10x+30y|
|              | -8x-22y  -47x-39y 16x+22y  15x-23y  -38x+33y -23x-7y -18x+39y|
|                                                                             |
|                            5                                                |
|o3 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|27x-22y  |                                                                   |
|32x-9y   |                                                                   |
|-32x-20y |                                                                   |
|24x-30y  |                                                                   |
|-48x-15y |                                                                   |
+-----------------------------------------------------------------------------+
|i4 : (N,f) = decomposeModule M                                               |
|                                                                             |
|o4 = (cokernel | y x 0 0 0 0 0 0 |, | -25 -49 -25 15  1   |)                 |
|               | 0 0 x 0 y 0 0 0 |  | 28  -45 29  30  -39 |                  |
|               | 0 0 0 y x 0 0 0 |  | -16 43  -43 -47 -24 |                  |
|               | 0 0 0 0 0 x 0 y |  | -14 -37 25  -19 26  |                  |
|               | 0 0 0 0 0 0 y x |  | 1   0   0   0   0   |                  |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : components N                                                            |
|                                                                             |
|o5 = {cokernel | y x |, cokernel | x 0 y |, cokernel | x 0 y |}              |
|                                 | 0 y x |           | 0 y x |               |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : ker f == 0                                                              |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : coker f == 0                                                            |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use decomposeModule:
============================

  * "decomposeModule(Module)"

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

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

doubleDualMap
*************

Ways to use doubleDualMap:
==========================

  * doubleDualMap(Module,Module) (missing documentation)

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

The object doubleDualMap (missing documentation) is a method function (Macaulay2Doc).

kroneckerIndices -- data which classify a matrix pencil up to strict equivalence
********************************************************************************

Synopsis
========

  * Usage:
        (L, dualL, d) = kroneckerIndices(P,x,y)
  * Inputs:
      * P, a matrix (Macaulay2Doc), a matrix of linear forms
      * x, a ring element (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc),
  * Outputs:
      * L, a list (Macaulay2Doc), degrees of minimal generators of
        the kernel
      * dualL, a list (Macaulay2Doc), degrees of minimal generators
        of the kernel of the dual
      * d, a list (Macaulay2Doc), elementary divisors

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

This function gives data which classify a matrix pencil up to strict
equivalence.  That is, these data determine the Kronecker normal form of the
pencil, up to rearranging the blocks.
+------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                              |
|                                                                  |
|o1 = R                                                            |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : A = matrix{{x,y,x,y},{y,x,y,x},{x,y,x,y},{y,y,y,y},{x,x,y,y}}|
|                                                                  |
|o2 = | x y x y |                                                  |
|     | y x y x |                                                  |
|     | x y x y |                                                  |
|     | y y y y |                                                  |
|     | x x y y |                                                  |
|                                                                  |
|             5      4                                             |
|o2 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i3 : kroneckerNormalForm(A, ChangeMatrix => {false,false})        |
|                                                                  |
|o3 = | 0 0 0   0   |                                              |
|     | 0 x 0   0   |                                              |
|     | 0 y 0   0   |                                              |
|     | 0 0 x-y 0   |                                              |
|     | 0 0 0   x-y |                                              |
|                                                                  |
|             5      4                                             |
|o3 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i4 : kroneckerIndices(A,x,y)                                      |
|                                                                  |
|o4 = ({0}, {0, 1}, {x - y, x - y})                                |
|                                                                  |
|o4 : Sequence                                                     |
+------------------------------------------------------------------+

Ways to use kroneckerIndices:
=============================

  * "kroneckerIndices(Matrix,RingElement,RingElement)"
  * kroneckerIndices(Matrix,Matrix)
    -- data classifying the normal form
    of a pair of matrices

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

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

kroneckerIndices(Matrix,Matrix) -- data classifying the normal form of a pair of matrices
*****************************************************************************************

Synopsis
========

  * Function: kroneckerIndices,
  * Usage:
        kroneckerIndices(A,B)
  * Inputs:
      * A, a matrix (Macaulay2Doc),
      * B, a matrix (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

  * kroneckerIndices(Matrix,Matrix)
    -- data classifying the normal form
    of a pair of matrices

kroneckerNormalForm -- Kronecker normal form of a matrix of linear forms
************************************************************************

Synopsis
========

  * Usage:
        (B,P,Q) = kroneckerNormalForm A
        (B,P) = kroneckerNormalForm(A,ChangeMatrix=>{true,false})
        (B,Q) = kroneckerNormalForm(A,ChangeMatrix=>{false,true})
        B = kroneckerNormalForm(A,ChangeMatrix=>{false,false})
        (B,P,Q) = kroneckerNormalForm(A,x,y)
        (B,P) = kroneckerNormalForm(A,x,y,ChangeMatrix=>{true,false})
        (B,Q) = kroneckerNormalForm(A,x,y,ChangeMatrix=>{false,true})
        B = kroneckerNormalForm(A,x,y,ChangeMatrix=>{false,false})
  * Inputs:
      * A, a matrix (Macaulay2Doc), a matrix of linear forms in
        two variables
      * x, a ring element (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ChangeMatrix => ..., default value {true, true}
  * Outputs:
      * B, a matrix (Macaulay2Doc), the Kronecker normal form of
        A
      * P, a matrix (Macaulay2Doc), invertible (left) change of
        basis matrix
      * Q, a matrix (Macaulay2Doc), invertible (right) change of
        basis matrix

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

This function produces a matrix of linear forms B, and invertible matrices P
and Q such that B = P*A*Q and B is in Kronecker normal form.  The optional
parameters x and y, if given, should be complementary linear forms. They are
used to fill in nonzero entries of all blocks in the Kronecker normal form for
which there is a choice of which linear forms to use. If they are not given,
they are assumed to be the first two variables of the ring.
+------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                              |
|                                                                  |
|o1 = R                                                            |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : A = matrix{{x,y,x,y},{y,x,y,x},{x,y,x,y},{y,y,y,y},{x,x,y,y}}|
|                                                                  |
|o2 = | x y x y |                                                  |
|     | y x y x |                                                  |
|     | x y x y |                                                  |
|     | y y y y |                                                  |
|     | x x y y |                                                  |
|                                                                  |
|             5      4                                             |
|o2 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i3 : (B,P,Q) = kroneckerNormalForm A                              |
|                                                                  |
|o3 = (| 0 0 0   0   |, | -1 0  1  0  0 |, {1} | -1 1 1  1  |)     |
|      | 0 x 0   0   |  | 0  1  1  -1 0 |  {1} | 1  0 0  -1 |      |
|      | 0 y 0   0   |  | 0  0  0  1  0 |  {1} | 1  0 -1 0  |      |
|      | 0 0 x-y 0   |  | 0  -1 -1 1  1 |  {1} | -1 0 0  0  |      |
|      | 0 0 0   x-y |  | 0  -1 0  1  0 |                          |
|                                                                  |
|o3 : Sequence                                                     |
+------------------------------------------------------------------+
|i4 : B - P*A*Q == 0                                               |
|                                                                  |
|o4 = true                                                         |
+------------------------------------------------------------------+
|i5 : kroneckerNormalForm(A, ChangeMatrix => {true,false})         |
|                                                                  |
|o5 = (| 0 0 0   0   |, | -1 0  1  0  0 |)                         |
|      | 0 x 0   0   |  | 0  1  1  -1 0 |                          |
|      | 0 y 0   0   |  | 0  0  0  1  0 |                          |
|      | 0 0 x-y 0   |  | 0  -1 -1 1  1 |                          |
|      | 0 0 0   x-y |  | 0  -1 0  1  0 |                          |
|                                                                  |
|o5 : Sequence                                                     |
+------------------------------------------------------------------+
|i6 : kroneckerNormalForm(A, ChangeMatrix => {false,true})         |
|                                                                  |
|o6 = (| 0 0 0   0   |, {1} | -1 1 1  1  |)                        |
|      | 0 x 0   0   |  {1} | 1  0 0  -1 |                         |
|      | 0 y 0   0   |  {1} | 1  0 -1 0  |                         |
|      | 0 0 x-y 0   |  {1} | -1 0 0  0  |                         |
|      | 0 0 0   x-y |                                             |
|                                                                  |
|o6 : Sequence                                                     |
+------------------------------------------------------------------+
|i7 : kroneckerNormalForm(A, ChangeMatrix => {false,false})        |
|                                                                  |
|o7 = | 0 0 0   0   |                                              |
|     | 0 x 0   0   |                                              |
|     | 0 y 0   0   |                                              |
|     | 0 0 x-y 0   |                                              |
|     | 0 0 0   x-y |                                              |
|                                                                  |
|             5      4                                             |
|o7 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i8 : (B,P,Q) = kroneckerNormalForm(A,x+y,x-y)                     |
|                                                                  |
|o8 = (| 0 0   0   0   |, | -1 0  1  0 0 |, {1} | -1 -2 1  1  |)   |
|      | 0 x+y 0   0   |  | 0  50 50 0 0 |  {1} | 1  0  0  -1 |    |
|      | 0 x-y 0   0   |  | 0  50 50 1 0 |  {1} | 1  0  -1 0  |    |
|      | 0 0   x-y 0   |  | 0  -1 -1 1 1 |  {1} | -1 0  0  0  |    |
|      | 0 0   0   x-y |  | 0  -1 0  1 0 |                         |
|                                                                  |
|o8 : Sequence                                                     |
+------------------------------------------------------------------+
|i9 : B - P*A*Q == 0                                               |
|                                                                  |
|o9 = true                                                         |
+------------------------------------------------------------------+

Ways to use kroneckerNormalForm:
================================

  * "kroneckerNormalForm(Matrix)"
  * "kroneckerNormalForm(Matrix,RingElement,RingElement)"
  * kroneckerNormalForm(Matrix,Matrix)
    -- normal form of a pair of
    matrices of scalars

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

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

kroneckerNormalForm(Matrix,Matrix) -- normal form of a pair of matrices of scalars
**********************************************************************************

Synopsis
========

  * Function: kroneckerNormalForm,
  * Usage:
        (A',B',P,Q) = kroneckerNormalForm(A,B)
  * Inputs:
      * A, a matrix (Macaulay2Doc),
      * B, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ChangeMatrix, => ..., default value {true,
        true}, Kronecker normal form of a matrix of linear forms
  * Outputs:
      * A', a matrix (Macaulay2Doc),
      * B', a matrix (Macaulay2Doc),
      * P, a matrix (Macaulay2Doc),
      * Q, a matrix (Macaulay2Doc),

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

This function gives the normal form of a pair of matrices (A,B) over a field of
the same dimensions up to multiplication on either side by an invertible
matrix.  The return values are such that P*A*Q=A' and P*B*Q=B'.
+-----------------------------------------------------------------------------+
|i1 : R = QQ                                                                  |
|                                                                             |
|o1 = QQ                                                                      |
|                                                                             |
|o1 : Ring                                                                    |
+-----------------------------------------------------------------------------+
|i2 : A = random(R^2, R^5)                                                    |
|                                                                             |
|o2 = | 9/2 9/4 1   3/2 7/4 |                                                 |
|     | 1/2 1/2 3/4 3/4 7/9 |                                                 |
|                                                                             |
|              2       5                                                      |
|o2 : Matrix QQ  <-- QQ                                                       |
+-----------------------------------------------------------------------------+
|i3 : B = random(R^2, R^5)                                                    |
|                                                                             |
|o3 = | 7/10 7/10 7   5/2 2/3 |                                               |
|     | 1/2  7/3  3/7 6/7 1   |                                               |
|                                                                             |
|              2       5                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
+-----------------------------------------------------------------------------+
|i4 : (A',B',P,Q) = kroneckerNormalForm(A,B)                                  |
|                                                                             |
|o4 = (| 0 1 0 0 0 |, | 0 0 1 0 0 |, | 0         -1/132721 |, | -40808        |
|      | 0 0 0 1 0 |  | 0 0 0 0 1 |  | -1/132721 0         |  | 202908        |
|                                                             | 2079708       |
|                                                             | -7142692      |
|                                                             | 4777956       |
|     ------------------------------------------------------------------------|
|     51928   25914  -37872 -1740  |)                                         |
|     121152  -76944 -3708  -7740  |                                          |
|     135492  -10962 -8932  -31530 |                                          |
|     -427840 44982  36652  37850  |                                          |
|     0       0      0      0      |                                          |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : P*A*Q - A' == 0                                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : P*B*Q - B' == 0                                                         |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

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

  * kroneckerNormalForm(Matrix,Matrix)
    -- normal form of a pair of
    matrices of scalars

rationalNormalForm -- rational normal form of a matrix
******************************************************

Synopsis
========

  * Usage:
        (B,P,Q) = rationalNormalForm A
        (B,P) = rationalNormalForm(A,ChangeMatrix=>{true,false})
        (B,Q) = rationalNormalForm(A,ChangeMatrix=>{false,true})
        B = rationalNormalForm(A,ChangeMatrix=>{false,false})
  * Inputs:
      * A, a matrix (Macaulay2Doc), a square matrix with constant
        entries
  * Optional inputs (Macaulay2Doc),:
      * ChangeMatrix => ..., default value {true, true}
  * Outputs:
      * B, a matrix (Macaulay2Doc), the rational normal form of A
      * P, a matrix (Macaulay2Doc), invertible (left) change of
        basis matrix
      * Q, a matrix (Macaulay2Doc), invertible (right) change of
        basis matrix

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

This function produces a matrix B in rational normal form, and invertible
matrices P and Q such that P*Q = I and B = P*A*Q.
+--------------------------------------------------------------+
|i1 : R = ZZ/101[x]                                            |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i2 : M = R^4                                                  |
|                                                              |
|      4                                                       |
|o2 = R                                                        |
|                                                              |
|o2 : R-module, free                                           |
+--------------------------------------------------------------+
|i3 : A = random(M,M)                                          |
|                                                              |
|o3 = | 24  19  -8  -38 |                                      |
|     | -36 19  -22 -16 |                                      |
|     | -30 -10 -29 39  |                                      |
|     | -29 -29 -24 21  |                                      |
|                                                              |
|             4      4                                         |
|o3 : Matrix R  <-- R                                          |
+--------------------------------------------------------------+
|i4 : factor det(x*id_M - A)                                   |
|                                                              |
|       2              2                                       |
|o4 = (x  + 39x - 10)(x  + 27x - 27)                           |
|                                                              |
|o4 : Expression of class Product                              |
+--------------------------------------------------------------+
|i5 : (B,P,Q) = rationalNormalForm A                           |
|                                                              |
|o5 = (| -27 1 0   0 |, | 15 -11 46  -1 |, | 50  13  7   -23 |)|
|      | 27  0 0   0 |  | 12 -46 -47 39 |  | -37 -24 -41 -18 | |
|      | 0   0 -39 1 |  | -9 47  33  -2 |  | 23  1   33  1   | |
|      | 0   0 10  0 |  | 41 -40 22  50 |  | -8  0   -47 0   | |
|                                                              |
|o5 : Sequence                                                 |
+--------------------------------------------------------------+
|i6 : B - P*A*Q == 0                                           |
|                                                              |
|o6 = true                                                     |
+--------------------------------------------------------------+
|i7 : P*Q - id_M == 0                                          |
|                                                              |
|o7 = true                                                     |
+--------------------------------------------------------------+

Ways to use rationalNormalForm:
===============================

  * "rationalNormalForm(Matrix)"

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

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