reduce-historical/r38/doc/help/normform.tex

\section{Matrix Normal Forms}

\begin{Operator}{Smithex}
The operator \name{smithex} computes the Smith normal form S of a
\nameref{matrix} A (say). It returns \{S,P,$P^-1$\} where $P*S*P^-1 = A$.

\begin{Syntax}
\name{smithex}\(\meta{matrix},\meta{variable}\)

\meta{matrix} :- a rectangular \nameref{matrix} of univariate polynomials in 
                 \meta{variable}.
\meta{variable} :- the variable.
\end{Syntax}

\begin{Examples}
 a := mat((x,x+1),(0,3*x^2)); &
\begin{multilineoutput}{6cm}
      [x  x + 1]
      [        ]
 a := [      2 ]
      [0  3*x  ]
\end{multilineoutput}\\

 smithex(a,x); &
\begin{multilineoutput}{6cm}
   [1  0 ]    [1    0]    [x   x + 1]
\{  [     ],   [      ],   [         ]  \}
   [    3]    [   2  ]    [         ]
   [0  x ]    [3*x  1]    [-3    -3 ]
\end{multilineoutput}\\
\end{Examples}
\end{Operator}


\begin{Operator}{Smithex\_int}
The operator \name{smithex\_int} performs the same task as \name{smithex}
but on matrices containing only integer entries. Namely, 
\name{smithex\_int} returns \{S,P,$P^-1$\} where S is the smith normal
form of the input \nameref{matrix} (A say), and $P*S*P^-1 = A$.

\begin{Syntax}
\name{smithex\_int}\(\meta{matrix}\)

\meta{matrix} :- a rectangular \nameref{matrix} of integer entries.
\end{Syntax}

\begin{Examples}
 a := mat((9,-36,30),(-36,192,-180),(30,-180,180)); &
\begin{multilineoutput}{6cm}
     [ 9   -36    30 ]
     [               ]
a := [-36  192   -180]
     [               ]
     [30   -180  180 ]
\end{multilineoutput}\\

 smithex_int(a); &
\begin{multilineoutput}{6cm}
  [3  0   0 ]    [-17  -5   -4 ]    [1   -24  30 ]
  [         ]    [             ]    [            ]
\{ [0  12  0 ],   [64   19   15 ],   [-1  25   -30] \}
  [         ]    [             ]    [            ] 
  [0  0   60]    [-50  -15  -12]    [0   -1    1 ] 
\end{multilineoutput}\\
\end{Examples}
\end{Operator}


\begin{Operator}{Frobenius}
The operator \name{frobenius} computes the \name{frobenius} normal form F of a 
\nameref{matrix} (A say). It returns \{F,P,$P^-1$\} where $P*F*P^-1 = A$.

\begin{Syntax}
\name{frobenius}\(\meta{matrix}\)

\meta{matrix} :- a square \nameref{matrix}.
\end{Syntax}

Field Extensions:

By default, calculations are performed in the rational numbers. To 
extend this field the \nameref{arnum} package can be used. The package must
first be loaded by load\_package arnum;. The field can now be extended
by using the defpoly command. For example, defpoly sqrt2**2-2; will
extend the field to include the square root of 2 (now defined by sqrt2).

Modular Arithmetic: 

\name{Frobenius} can also be calculated in a modular base. To do this 
first type on  modular;. Then setmod p; (where p is a prime) will set 
the modular base of calculation to p. By further typing on balanced\_mod
the answer will appear using a symmetric modular representation. See 
\nameref{ratjordan} for an example.

\begin{Examples}
 a := mat((x,x^2),(3,5*x)); &
\begin{multilineoutput}{6cm}
     [    2 ]
     [x  x  ]
a := [      ]
     [3  5*x]
\end{multilineoutput}\\
 frobenius(a);&
\begin{multilineoutput}{6cm}
   [         2]    [1  x]    [       - x ]
\{  [0   - 2*x ],   [    ],   [1     -----]  \}
   [          ]    [0  3]    [        3  ]
   [1    6*x  ]              [           ]
                             [        1  ]
                             [0      --- ]
                             [        3  ]

\end{multilineoutput}\\
 load\_package arnum;\\
 defpoly sqrt2**2-2;\\
 a := mat((sqrt2,5),(7*sqrt2,sqrt2));&
\begin{multilineoutput}{6cm}
     [ sqrt2     5  ]
a := [              ]
     [7*sqrt2  sqrt2]
\end{multilineoutput}\\

 frobenius(a); &
\begin{multilineoutput}{6cm}
  [0  35*sqrt2 - 2]    [1   sqrt2 ]    [           1  ]
\{ [               ],   [          ],   [1       - --- ]  \}
  [1    2*sqrt2   ]    [1  7*sqrt2]    [           7  ]
                                       [              ]
                                       [     1        ]
                                       [0   ----*sqrt2]
                                       [     14       ]

\end{multilineoutput}\\
\end{Examples}
\end{Operator}



\begin{Operator}{Ratjordan}
The operator \name{ratjordan} computes the rational Jordan normal form R
of a \nameref{matrix} (A say). It returns \{R,P,$P^-1$\} where $P*R*P^-1 = A$.

\begin{Syntax}
\name{ratjordan}\(\meta{matrix}\)

\meta{matrix} :- a square \nameref{matrix}.
\end{Syntax}

Field Extensions:

By default, calculations are performed in the rational numbers. To 
extend this field the \name{arnum} package can be used. The package must
first be loaded by  load\_package arnum;. The field can now be extended
by using the defpoly command. For example, defpoly sqrt2**2-2; will
extend the field to include the square root of 2 (now defined by sqrt2).
See \nameref{frobenius} for an example.

Modular Arithmetic:

\name{ratjordan} can also be calculated in a modular base. To do this 
first type on  modular;. Then setmod p; (where p is a prime) will set 
the modular base of calculation to p. By further typing on balanced\_mod
the answer will appear using a symmetric modular representation.

\begin{Examples}
 a := mat((5,4*x),(2,x^2));&
\begin{multilineoutput}{6cm}
     [5  4*x]
     [      ]
a := [    2 ]
     [2  x  ]
\end{multilineoutput}\\

 ratjordan(a); &
\begin{multilineoutput}{6cm}
  [0  x*( - 5*x + 8)]   [1  5]    [        -5 ]  
\{ [                 ],  [    ],   [1     -----] \}
  [        2        ]   [0  2]    [        2  ]
  [1      x  + 5    ]             [           ]
                                  [        1  ]
                                  [0     -----]
                                  [        2  ]
\end{multilineoutput}\\
 on modular; \\
 setmod 23; \\
 a := mat((12,34),(56,78)); &
\begin{multilineoutput}{6cm}
     [12  11]
a := [      ]
     [10  9 ]
\end{multilineoutput}\\

 ratjordan(a); &
\begin{multilineoutput}{6cm}
  [15  0]   [16  8]   [1  21]
\{ [     ],  [     ],  [     ]  \}
  [0   6]   [19  4]   [1  4 ]
\end{multilineoutput}\\

 on balanced\_mod;\\
 ratjordan(a);&
\begin{multilineoutput}{6cm}
  [- 8  0]   [ - 7  8]   [1  - 2]
\{ [      ],  [       ],  [      ]  \}
  [ 0   6]   [ - 4  4]   [1   4 ]
\end{multilineoutput}\\

\end{Examples}
\end{Operator}



\begin{Operator}{Jordansymbolic}
The operator \name{jordansymbolic} computes the Jordan normal form J
of a \nameref{matrix} (A say). It returns \{J,L,P,$P^-1$\} where
$P*J*P^-1 = A$. L = \{ll,mm\} where mm is a name and ll is a list of
irreducible factors of p(mm).

\begin{Syntax}
\name{jordansymbolic}\(\meta{matrix}\)

\meta{matrix} :- a square \nameref{matrix}.
\end{Syntax}

Field Extensions:

By default, calculations are performed in the rational numbers. To 
extend this field the \nameref{arnum} package can be used. The package must
first be loaded by  load\_package arnum;. The field can now be extended
by using the defpoly command. For example, defpoly sqrt2**2-2; will
extend the field to include the square root of 2 (now defined by sqrt2).
See \nameref{frobenius} for an example.

Modular Arithmetic:

\name{jordansymbolic} can also be calculated in a modular base. To do this 
first type on  modular;. Then setmod p; (where p is a prime) will set 
the modular base of calculation to p. By further typing on balanced\_mod
the answer will appear using a symmetric modular representation. See 
\nameref{ratjordan} for an example.

% Extras:

% If using \name{xr}, the X interface for REDUCE, then the appearance of the
% output can be improved by switching on looking\_good. This
% converts any lambdas to a greek font.

\begin{Examples}

 a := mat((1,y),(2,5*y)); &
\begin{multilineoutput}{6cm}
     [1   y ]
a := [      ]
     [2  5*y]
\end{multilineoutput}\\

 jordansymbolic(a); &
\begin{multilineoutput}{6cm}
\{

 [lambda11     0    ]
 [                  ]
 [   0      lambda12]

 ,

         2
 {{lambda  - 5*lambda*y - lambda + 3*y},lambda},


 [lambda11 - 5*y  lambda12 - 5*y]
 [                              ]
 [      2               2       ]

 ,


 [ 2*lambda11 - 5*y - 1    5*lambda11*y - lambda11 - y + 1 ]
 [----------------------  ---------------------------------]
 [       2                              2                  ]
 [   25*y  - 2*y + 1             2*(25*y  - 2*y + 1)       ]
 [                                                         ]
 [ 2*lambda12 - 5*y - 1    5*lambda12*y - lambda12 - y + 1 ]
 [----------------------  ---------------------------------]
 [       2                              2                  ]
 [   25*y  - 2*y + 1             2*(25*y  - 2*y + 1)       ]

 \}

\end{multilineoutput}\\
\end{Examples}
\end{Operator}



\begin{Operator}{Jordan}
The operator \name{jordan} computes the Jordan normal form J
of a \nameref{matrix} (A say). It returns \{J,P,$P^-1$\} where $P*J*P^-1 = A$.

\begin{Syntax}
\name{jordan}\(\meta{matrix}\)

\meta{matrix} :- a square \nameref{matrix}.
\end{Syntax}

Field Extensions:
By default, calculations are performed in the rational numbers. To 
extend this field the \name{arnum} package can be used. The package must
first be loaded by  load\_package arnum;. The field can now be extended
by using the defpoly command. For example, defpoly sqrt2**2-2; will
extend the field to include the square root of 2 (now defined by sqrt2).
See \nameref{frobenius} for an example.

Modular Arithmetic:
\name{Jordan} can also be calculated in a modular base. To do this 
first type on  modular;. Then setmod p; (where p is a prime) will set 
the modular base of calculation to p. By further typing on balanced\_mod
the answer will appear using a symmetric modular representation. See
\nameref{ratjordan} for an example.

\begin{Examples}

 a := mat((1,x),(0,x)); &
\begin{multilineoutput}{6cm}
     [1  x]
a := [    ]
     [0  x]
\end{multilineoutput}\\

 jordan(a);&
\begin{multilineoutput}{6cm}
\{

 [1  0]
 [    ]
 [0  x]

 ,


 [   1           x       ]
 [-------  --------------]
 [ x - 1     2           ]
 [          x  - 2*x + 1 ]
 [                       ]
 [               1       ]
 [   0        -------    ]
 [             x - 1     ]

 ,


 [x - 1   - x ]
 [            ]
 [  0    x - 1]

 \}
\end{multilineoutput}\\
\end{Examples}

\end{Operator}