%%
%% ch6.tex
%%

\chapter{Matrices}
\label{ch-matrices}

A matrix in \Macaulay\ is a matrix of polynomials over some polynomial
ring.  In this chapter, we describe the operations available for
computing with matrices which don't require standard bases.  These
range from matrix input and output, to simple operations such as
addition and multiplication of matrices, to relatively esoteric
operations such as \icmd{koszul} or \icmd{contract}.

Matrices have several interpretations in \Macaulay.  Let $M$ be an $m$
by $n$ matrix of polynomials over the ring $R$.  There are two
$R$-modules which we can associate to $M$.  First, the submodule $I
\subset R^m$ is the submodule of $R^m$ generated by the columns of the
matrix $M$.  This interpretation is used heavily when dealing with
standard (\Grobner) bases.  We call $I$ the ``submodule generated by the
columns of the matrix $M$''.  The second module corresponding to $M$ is the
module $N$ which is presented by $M$.  That is, The $R$-module $N$ has $m$
generators, one for each row of $M$, and the relations between these 
generators are exactly the columns of the matrix $M$.  This interpretation
is used often, although not as much as the first.  For example, the 
\icmd{hilb} command computes the Hilbert series of the module presented by
a matrix.

Each matrix in \Macaulay\ must be defined over a specific base ring.  This
is required so that the standard basis and syzygy computations which are the
heart of \Macaulay\ can be highly optimized.  Every command in this chapter
(indeed, every command of \Macaulay) can be used with all rings of \Macaulay.
In particular, each command works fine over a quotient ring. 

Every operation described in this chapter remains valid even if the 
input matrices are not graded.  In fact, the only commands of \Macaulay\
where this is false are the computation commands (see \chapref{ch-comps}).

Some additional notes valid for all matrix commands:
\begin{itemize}
\item Matrices with zero rows or columns (or both) are allowed
as parameters (when they make sense, e.g. one can multiply a 3 by 0,
and a 0 by 4 matrix to obtain a 3 by 4 matrix.  This is useful for
writing scripts.

\item Result variables can be given the same name as an
argument: e.g. the command ``{\tt add m n m}'' computes $m+n$, and
then removes the old matrix $m$, and finally stores the result $m+n$
with the name $m$.

\item As usual thoughout \Macaulay, whenever an integer is
expected as an argument, or is prompted for, one may use any integer
expression.
\end{itemize}

The following two commands display the number of rows or columns of a
given matrix.  They are most useful in conjunction with scripts.  See
also the \icmd{numinfo} and \icmd{betti} commands: they display more
information.

\cmd {nrows} {\parm {matrix} \optparm {result integer}}
\label{c-nrows} % nrows  Number of rows of a matrix

Set the result integer variable, if given, to the number of rows of
the matrix.  If an integer is not specified, display the number of rows.

\cmd {ncols} {\parm {matrix} \optparm {result integer}}
\label{c-ncols} % ncols  Number of columns of a matrix

Set the result integer variable, if given, to the number of columns of
the matrix.  If an integer is not specified, display the number of columns.

\section{Matrix creation}
\label{sec-minput}

There are four commands for creating matrices interactively:
\icmd{mat}, \icmd{poly}, \icmd{ideal} and \icmd{sparse}.  These prompt
the user for input polynomials.  The resulting matrix for each of these
commands has the current ring as its base ring.

\cmd{ideal}{\parm{result matrix}}
\label{c-ideal} % ideal  Interactively create an ideal (1 by $n$ matrix)

In \Macaulay, ideals are represented as matrices with a single row.
The \icmd{ideal} command is provided to allow you to simply specify
the generators for the ideal.  First, you are prompted for the number of
generators.  Subsequently, the system prompts for the generators one
at a time creating a 1 by $n$ matrix, where $n$ is the number of
generators.  The generators are input as polynomials in the current
ring.  The base ring of the resulting matrix is the current ring.

\cmd{mat}{\parm{result matrix} \optparm{file name}}
\label{c-mat} % mat  Interactively create a matrix

Interactively create a matrix over the current ring.  You are first
prompted for the number of rows, and then columns.  Any integer
expression is allowed.  \Macaulay\ then prompts for each entry of the
matrix column by column.  Each entry should be a polynomial expression
in the base ring.

If a file name is specified, the command uses this file as input, and
the system doesn't display any prompt lines.  Thus {\tt "mat m file"}
is the same as {\tt "mat m <file"}, where the input has been
redirected to come from ``file'', except that no prompts are displayed.

For example, to define a 2 by 3 matrix named $m$,
\begin{verbatim}
%  mat m
! number of rows    ?  2
! number of columns ?  3
! (1,1) ?  a2-b2
! (2,1) ?  (a+b)^2
! (1,2) ?  2c
! (2,2) ?  3d
! (1,3) ?  0
! (2,3) ?  (a+b)(c-d)

%  type m
; a2-b2     2c 0           
; a2+2ab+b2 3d ac+bc-ad-bd 

\end{verbatim}

The \icmd{putmat} command outputs matrices in a format suitable to be
input to the \icmd{mat} command.  Thus, one can use \icmd{putmat} to
output matrices to a disk, and then read them at another time using
\icmd{mat}.

For more information about degrees of rows, columns, and graded matrices,
see \secref{sec-mgraded}.

\cmd {poly} {\parm{result matrix} \parm{polynomial}}
\label{c-poly} % poly  Create a polynomial (1 by 1 matrix)

Set \parm{result} with the $1$ by $1$ matrix over the current ring consisting
of the given polynomial expression.  For example,

\begin{verbatim}
%  poly f (a+b)*(a-b)

%  type f
; a2-b2 

%  poly f {f}^2

%  type f
; a4-2a2b2+b4 

\end{verbatim}

In order to use a previously defined polynomial, its name must be enclosed
in curly braces.  This prevents name conflicts with ring variables.
See \secref{sec-sypoly} for more details.

\cmd{sparse}{\parm{result matrix} \optparm{file name}}
\label{c-sparse} % sparse  Interactively create a sparse matrix

Interactively create a sparse matrix over the current ring.   The
system first prompts for the number of rows and columns, and then
prompts for the index and polynomial value of each non-zero entry.

If a file name is given, the command uses this file as input, and the
system doesn't display any prompt lines.  Thus {\tt "sparse m file"}
is the same as {\tt "sparse m <file"}, where the input has been
redirected to come from ``file'', except that no prompts are displayed.

For example, to create a 5 by 6 matrix named $m56$,

\begin{verbatim}
%  sparse m56
! number of rows    ?  5
! number of columns ?  6
! row column value  ?  1 1 a2+b2+cd
! row column value  ?  3 5 abc
! row column value  ?  5 6 -1
! row column value  ? <return>

%  type m
; a2-b2     2c 0           
; a2+2ab+b2 3d ac+bc-ad-bd 

\end{verbatim}

The row, column, and polynomial expression are separated by blanks.
The row and column can be any integer expressions.
To stop the input of entries, simply type \return\ on your terminal.
The remaining entries are set to zero.

The base ring of the matrix is the current ring.

\section{Displaying Matrices}
\label{sec-moutput}

\cmd {type} {\parm{matrix}}

Display the given matrix on the user's screen.  This is the usual
method of viewing matrices which are not too large.  If an entry of
the matrix is large, \icmd{putmat} is sometimes preferable.

\cmd {putmat} {\parm{matrix}}
\label{c-putmat} % putmat  Write matrix in form suitable for \Macaulay\ input

Write to standard output the matrix in a format suitable to read by
\icmd{mat}.  For example, {\tt "putmat m >file"} writes to the 
file ``file''.  One can then use {\tt "mat m <file"}, or {\tt "mat m
file"} to read this matrix in at a later time.  Caution: before using
this command with a file, make sure you have defined the desired current
polynomial ring!

For example,

\begin{verbatim}
%  type m
; a b 
; c d 

%  putmat m
; 2
; 2
; a
; c
; b
; d

\end{verbatim}

The leading semicolons will not appear if a file name is given.

\cmd {prmat} {\parm{matrix}}
\label{c-prmat} % prmat  Write matrix in mathematica format

Writes the matrix in a format suitable for input to the Mathematica system.

One word of warning: Certain variable names can cause problems.  For
example, any indexed variable using ``D'': eg. D[1]. In Mathematica,
D[1] is the derivative of the function ``1'', so $D[1] = 0$.  The
letters which are used in Mathematica are: ``D'', ``E'', ``I'', ``N'',
and ``O''.  When inputting the matrix to Mathematica, the following
problem can occur.  If an identifier, say ``a'' already has a value,
then every occurence of ``a'' in the matrix will be replaced with this
value.

\begin{verbatim}
%  type m
; a     ab-1/3c -12       
; b2-c2 0       a3+a2+a+1 

%  prmat m
{
  {a,
    a*b-1/3*c,
    -12},
  {b^2-c^2,
    0,
    a^3+a^2+a+1}
}

\end{verbatim}


\section{Operations on matrices}
\label{sec-mops}

\cmd{add}{\parm{matrix} \parm{matrix} \parm{result}}
\label{c-add} % add  Add two matrices

Add two $m$ by $n$ matrices having the same base ring
and store the result in an $m$ by $n$ matrix.

\cmd{cat}{\parm{ring variable or integer} \parm{result matrix}}
\label{c-cat} % cat Create a matrix consisting of indeterminates

Create a matrix consisting of indeterminates. The first argument is
either a ring indeterminate in the current ring, or an integer. 
The user is prompted for two integer lists: call them rows, and cols.  The
result matrix is then the matrix whose $(i,j)$ entry is
	$$v[rows(i)+cols(j)],$$
where $v[k]$ is the $k$ th ring indeterminate:
\begin{enumerate}
\item if the first argument is a ring variable, then $v[k]$ is the $k$ th
variable after the given ring variable.
\item  if the first argument is an integer, $n$ say, then $v[k]$ is the 
$n+k$ th variable of the ring.
\end{enumerate}

For example, if the variables of the current ring are {\tt abcdefghij}, then

\begin{verbatim}
%  cat a m
! rows ?  0 3 6
! columns ?  0 1 2

%  type m
; a b c 
; d e f 
; g h i 

\end{verbatim}

Note: if $i$ is an integer variable, then ``{\tt cat i m}'' takes the ring
indeterminate $i$.  To get the integer $i$, use ``\verb|cat {i} m|''.

This command is very useful for creating ``generic'' matrices.

\cmd{coef}{\parm{matrix} \parm{result matrix} \optparm{variable list}}
\label{c-coef} % coef  Find the coefficients in a subset of variables in a matrix.

Find the monomials in the given variable list which occur in \parm{matrix},
and return a $1$ by $n$ matrix consisting of these monomials, and another
matrix consisting of the coefficients of these monomials.

If \parm{matrix} has just one column, then the result coef matrix has
the same number of rows as \parm{matrix} and $n$ columns, one for each
monomial.  If \parm{matrix} has several columns, the result is the
concatenation of the results for each column done separately.

For example,

\begin{verbatim}
%  type m
; abc2+abcd+a2d 
; a2e+1         
; b2+1          

%  coef m monoms coefs a b

%  type monoms 
; ab a2 b2 1 

%  type coefs
; c2+cd d 0 0 
; 0     e 0 1 
; 0     0 1 1 

\end{verbatim}

Caution: The default variable list, if none is given, is the first block 
of variables in the base ring of \parm{matrix}.  To find the coefficients
in all of the variables, use ``!'': e.g. \verb|coef m monoms coefs !|.  For
more details see \secref{sec-varlist}.

\cmd {compress} {\parm{matrix} \parm{result matrix}}
\label{c-compress} % compress  Remove every zero column from a matrix

Create a new matrix which is the submatrix of \parm{matrix} consisting
of those columns which have a non-zero entry.
For example,

\begin{verbatim}
%  type m
; 0 a 0 
; 0 b 0 

%  compress m n

%  type n
; a 
; b 

\end{verbatim}

\cmd{concat}{\parm{matrix} \parm{matrix2} ... \parm{matrix n}}
\label{c-concat} % concat  Concatenate a set of matrices, modifying the first

Replace \parm{matrix} with the concatenation of all $n$ matrices.  Every
matrix should have the same number of rows and the same base ring.
The result matrix has the same number of rows, but it has a column for
each column of each matrix. These columns are placed into \parm{matrix} in
the natural order.

The row degrees of the result matrix are exactly the same as the
original \parm{matrix}.  The column degrees have likewise been concatenated
together.  So, if the row degrees of the various matrices are
different, then the resulting matrix is probably not graded: use
\icmd{setdegs}, or \icmd{setcoldegs} to correct this.

For example,

\begin{verbatim}
%  type m
; a2 
; b2 

%  type m1
; a b 
; c d 

%  concat m m1

%  type m
; a2 a b 
; b2 c d 

\end{verbatim}

Caution: this command is ``destructive'':  the first argument is actually 
modified.  An error is reported if the matrix being modified also appears
later in the argument list.

\cmd{contract}{\parm{ideal I} \parm{ideal J} \parm{result matrix}}
\label{c-contract} % contract  Compute the contraction of one ideal by another

Contract each element of a $1$ by $n$ matrix $J$ by each element of the
$1$ by $m$ matrix $I$, producing a $m$ by $n$ matrix.  Both matrices
must have the same base ring.

Contraction is defined on monomials by 
	$$ x^A . x^B = \left\{ \begin{array}{ll}
				 x^{B-A} & \mbox{if $B-A \geq 0$} \\
				 0	 & \mbox{otherwise}
				\end{array}
			\right.
	$$
and is extended bilinearly to all polynomials.  For example, 
$x^2yz.x^3y^2z = xy$.

This is exactly the same as  \icmd{diff}, except that
contraction is used instead of differentiation.  E.g. $a^2.a^3 = a$,
{\bf not} $6a$.

For example,

\begin{verbatim}
%  type i
; a2 a2+bc abc 

%  type j
; a2-bc abcd 

%  contract i j k

%  type k
; 1 0  
; 0 ad 
; 0 d  

\end{verbatim}

\cmd{copy}{\parm{existing matrix} \parm{copy of matrix}}
\label{c-copy} % copy  Create a carbon copy of a matrix

Create a copy of the original matrix.  If any changes are made to either
matrix, the other will not be affected.

\cmd{diag}{\parm{matrix} \parm{result}}
\label{c-diag} % diag  Form the diagonal matrix with entries taken from a matrix

Takes an $m$ by $n$ matrix and places into \parm{result} the $m n$ by
$m n$ diagonal matrix whose diagonal entries are all the entries of
\parm{matrix}.  The diagonal entries of the result are taken from the
first column, then the second, and so on, as in the following example.

\begin{verbatim}
%  type m
; a c 
; b d 

%  diag m n

%  type n
; a 0 0 0 
; 0 b 0 0 
; 0 0 c 0 
; 0 0 0 d 

\end{verbatim}

\cmd{diff}{\parm{ideal I} \parm{ideal J} \parm{result matrix}}
\label{c-diff} % diff  Differentiate one ideal by another

Differentiate each element of a $1$ by $n$ matrix $J$ by 
the differential operator corresponding to each element of the
$1$ by $m$ matrix $I$, producing a $m$ by $n$ matrix.  Both matrices
must have the same base ring.

This is exactly the same as \icmd{contract}, except that
differentiation is used instead of contraction.  For example, 
$a^2.a^3 = 6a$.

For example,

\begin{verbatim}
%  type i
; a2 a2+bc abc 

%  type j
; a2-bc abcd 

%  diff i j k

%  type k
; 2 0  
; 1 ad 
; 0 d  

\end{verbatim}

\cmd{dsum}{\parm{matrix} ... \parm{matrix} \parm{result}}
\label{c-dsum} % dsum Create the direct sum of a set of matrices

Place into \parm{result} the direct sum of the given matrices, i.e.
the block diagonal matrix with the i th block being the i th matrix.

For example,

\begin{verbatim}
%  type m
; a b 
; c d 

%  type n
; a2+b2 ab-cd 

%  dsum m n n p

%  type p
; a b 0     0     0     0     
; c d 0     0     0     0     
; 0 0 a2+b2 ab-cd 0     0     
; 0 0 0     0     a2+b2 ab-cd 

\end{verbatim}

\cmd{flatten}{\parm{matrix} \parm{result ideal of entries}}
\label{c-flatten} % flatten  Create the ideal of all entries of a matrix

Create the row vector consisting of all the entries of the given $m$ by $n$
matrix.  The resulting matrix has size 1 by $m n$.  The elements
of \parm{matrix} are taken from the first column, then the second, and so 
on, as in the following example.

\begin{verbatim}
%  type m
; a c e 
; b d f 

%  flatten m n

%  type n
; a b c d e f 

\end{verbatim}

\cmd{homog}{\parm{matrix} \parm{homog variable} \parm{result matrix}}
\label{c-homog} % homog  Homogenize the columns of a matrix

Homogenize the columns of \parm{matrix} w.r.t. the homogenizing variable,
which must be a ring indeterminate in the base ring of \parm{matrix} having
weight one.

For example, if a, b, d all have weight one in the current ring, then

\begin{verbatim}
%  type m
; a3  a+3 -a3+ab+1 
; a-1 a-2 b5       

%  homog m d n

%  type n
; a3     a+3d -a3d2+abd3+d5 
; ad2-d3 a-2d b5            

\end{verbatim}

\cmd{iden}{\parm{size} \parm{result}}
\label{c-iden} % iden Create an identity matrix

Creates a \parm{size} by \parm{size} identity matrix over the current
ring.  The row and column degrees are all set to $0$.  Use \icmd{setdegs} to
change them, if desired.

\cmd{jacob}{\parm{ideal} \parm{resulting jacobian} \optparm{variable list}}
\label{c-jacob} % jacob Find the Jacobian matrix of an ideal

Compute the Jacobian matrix of a $1$ by $n$ matrix, w.r.t. the given set
of variables.  The resulting matrix has $n$ rows, and $m$ columns, where $m$
is the number of variables given in the variable list.  The $(i,j)$
entry is then the derivative of the $i$ th polynomial in \parm{ideal} by the
$j$ th variable in the given set of variables.  

For example, 

\begin{verbatim}
%  type j
; a2-bc abcd 

%  jacob j k a..d

%  type k
; 2a  -c  -b  0   
; bcd acd abd abc 

\end{verbatim}

In the first example, if instead of {\tt a..d}, one used {\tt d c b
a}, the exact same answer would result, since variable lists are
unordered.

Caution: The default variable list, if none is given, is the first
block of variables in the base ring of \parm{ideal}.  To find the
derivatives with respect to all of the variables, use ``!'': e.g.
\verb|jacob m Dm !|.  For more details see \secref{sec-varlist}.

\cmd{koszul}{\parm{int n, or matrix} \parm{p} \parm{result matrix}}
\label{c-koszul} % koszul Create a matrix in the Koszul complex

Create a Koszul matrix.  If the first argument is a matrix, it should
be a $1$ by $n$ matrix, for some $n$.  If an integer is given, the input
matrix is set to the $1$ by $n$ matrix consisting of the first $n$ variables
in the current ring.

The result matrix is the matrix corresponding to the map
	$$\bigwedge^p V \longrightarrow \bigwedge^{p-1} V,$$
where $V$ is free of rank $n$, and the map is induced from the input matrix.
The resulting matrix has dimensions $n\choose {p-1}$ by $n\choose p$.

For example, if the first $4$ variables in the current ring are {\tt abcd},
then

\begin{verbatim}
%  koszul 4 2 n

%  type n
; b  c  d  0  0  0  
; -a 0  0  c  d  0  
; 0  -a 0  -b 0  d  
; 0  0  -a 0  -b -c 

\end{verbatim}

\cmd{mult}{\parm{matrix 1} \parm{matrix 2} \parm{result}}
\label{c-mult} % mult  Multiply two matrices

Multiply a $p$ by $q$ matrix by a $q$ by $r$ matrix, producing a $p$ by
$r$ matrix.  Both matrices must have the same base ring.

\cmd{outer}{\parm{matrix} \parm{matrix} \parm{result matrix}}
\label{c-outer} % outer  Find the outer, or tensor product of two matrices

Compute the outer (or Kronecker) product of two matrices.  If the matrices
have sizes $a$ by $b$ and $c$ by $d$ respectively, then the result has size
$a c$ by $b d$.

For example, 

\begin{verbatim}
%  type m
; a b 
; c d 

%  type n
; e f g 
; h i j 
; k l m 

%  outer m n p

%  type p
; ae af ag be bf bg 
; ah ai aj bh bi bj 
; ak al am bk bl bm 
; ce cf cg de df dg 
; ch ci cj dh di dj 
; ck cl cm dk dl dm 

\end{verbatim}

\cmd{pfaff}{\parm{skew matrix} \parm{result ideal}}
\label{c-pfaff} % pfaff  Find the 4 by 4 Pfaffians of a skew matrix

Given an $n$ by $n$ skew symmetric matrix, compute the $1$ by 
$n\choose 4$ matrix of all the $4$ by $4$ Pfaffians of the matrix. 
Recall that the Pfaffian of a $4$ by $4$ skew symmetric matrix is the 
square root of its determinant.

For example,

\begin{verbatim}
%  type m
; 0  a  b  c  d 
; -a 0  e  f  g 
; -b -e 0  h  i 
; -c -f -h 0  j 
; -d -g -i -j 0 

%  pfaff m j

%  type j
; ce-bf+ah de-bg+ai df-cg+aj dh-ci+bj gh-fi+ej 

\end{verbatim}

\cmd{power}{\parm{matrix} \parm{integer d} \parm{result matrix}}
\label{c-power} % power  Find the dth power of an ideal

Take a $1$ by $n$ matrix and returns a $1$ by ${n+d-1}\choose {n-1}$
matrix consisting of all products of these polynomials taken $d$ at a
time.  The products are constructed in descending lexicographic order.

For example,

\begin{verbatim}
%  type m
; a b c d 

%  power m 2 m2

%  type m2
; a2 ab ac ad b2 bc bd c2 cd d2 

\end{verbatim}

\cmd{random}{\parm{integer m} \parm{integer n} \parm{result matrix}}
\label{c-random} % random Create a matrix with random constant entries

Create a $m$ by $n$ matrix with random constant entries over the
current ring.

For example,

\begin{verbatim}
%  random 2 3 m

%  type m
; -1955 2555 3982 
; 3748  1719 8651 

\end{verbatim}

\cmd{smult}{\parm{matrix} \parm{polynomial} \parm{result}}
\label{c-smult} % smult Multiply a polynomial by a matrix

Multiply each entry of the $m$ by $n$ matrix by the polynomial and
store the result in an $m$ by $n$ matrix.  The polynomial must be in
the base ring of the matrix.

For example,

\begin{verbatim}
%  type m
; a b 
; c d 

%  smult m (d+e)^2 n

%  type n
; ad2+2ade+ae2 bd2+2bde+be2 
; cd2+2cde+ce2 d3+2d2e+de2  

\end{verbatim}

\cmd{subtract}{\parm{matrix 1} \parm{matrix 2} \parm{result}}
\label{c-subtract} % subtract Subtract one matrix from another

This command subtracts the $m$ by $n$ \parm{matrix 2} from the $m$ by $n$
\parm{matrix 1} and stores the result in an $m$ by $n$ matrix.

\cmd{submat}{\parm{matrix} \parm{result submatrix}}
\label{c-submat} % submat Find a submatrix

Put a submatrix of \parm{matrix} into \parm{result submatrix}.  The user
is prompted for integer lists describing exactly which rows and columns
to choose.

In the following example, we choose the first two rows of the matrix $m$,
and the last two columns of $m$ permuted.

\begin{verbatim}
%  type m
; a b c d 
; e f g h 
; i j k l 

%  submat m n
! rows ?  3 2
! columns ?  1..3

%  type n
; i j k 
; e f g 

\end{verbatim}

If \return\ is entered for the row (or column) integer list,
then every row (or column) is selected.  Notice that this command can
be used to permute the rows or columns of a matrix.

\cmd{tensor}{\parm{matrix M} \parm{matrix N} \parm{result matrix}}
\label{c-tensor} % tensor Compute the tensor product of two modules

Compute the tensor product of the modules presented by the matrices M,
N: If M is an $a$ by $b$ matrix, and N is a $c$ by $d$ matrix, then the
result is a matrix with $a c$ rows, and $b c + a d$ columns, which is the
matrix which presents the tensor product of the two modules.

For example, 

\begin{verbatim}
%  type m
; a b 
; c d 

%  type n
; e f g 
; h i j 
; k l m 

%  tensor m n p

%  type p
; e f g 0 0 0 a b 0 0 0 0 
; h i j 0 0 0 0 0 a b 0 0 
; k l m 0 0 0 0 0 0 0 a b 
; 0 0 0 e f g c d 0 0 0 0 
; 0 0 0 h i j 0 0 c d 0 0 
; 0 0 0 k l m 0 0 0 0 c d 

\end{verbatim}

\cmd{transpose}{\parm{matrix} \parm{result matrix}}
\label{c-transpose} % transpose Transpose a matrix

Transpose the $m$ by $n$ matrix and store the result in an $n$ by $m$
matrix.  The row and column degrees are interchanged and negated, in
order to keep the result matrix graded, assuming the input matrix is also 
graded.

\cmd{trace}{\parm{matrix} \parm{resulting trace}}
\label{c-trace} % trace Find the trace of a matrix

Sets the 1 by 1 matrix \parm{result} with the sum of the diagonal 
entries of the $m$ by $n$ \parm{matrix}.

\cmd{wedge}{\parm{matrix M} \parm{integer p} \parm{result matrix}}
\label{c-wedge} % wedge Find all the p by p determinants of a matrix

Compute the determinants of all the $p$ by $p$ minors of the given $m$
by $n$ matrix. The resulting matrix $\wedge^p M$ has size $m\choose p$
by $n\choose p$.  The signs are chosen so that if C = A.B, where $A$
and $B$ are matrices, then $\wedge^p C = \wedge^p A \wedge^p B$.

For example,

\begin{verbatim}
%  type m
; a b c 
; d e f 
; g h i 

%  wedge m 2 n

%  type n
; -bd+ae cd-af  -ce+bf 
; bg-ah  -cg+ai ch-bi  
; -eg+dh fg-di  -fh+ei 

\end{verbatim}

Use the \icmd{flatten} command to find the ideal of all of these
determinants.

\section{Editing Commands }
\label{sec-medit}

The commands in this section all modify a previously defined matrix.
They are often useful to simplify a matrix, or to change a single
entry of a matrix.  In order to use these commands, you must first use
the \icmd{edit} command to tell \Macaulay\ which matrix you wish to
edit.  This ``edit matrix'' is kept as the matrix to modify until either
you select a different matrix, or the variable is removed.

\cmd {edit} {\optparm {matrix}}
\label{c-edit} % edit Set the ``edit matrix''

Set the ``edit matrix'' to be the specified matrix.  Subsequently, the
commands \icmd{ac}, \icmd{ar}, \icmd{ce}, \icmd{mc}, \icmd{mr}, \icmd{pc},
and \icmd{pr} will act on and modify this matrix.

If no matrix is specified, the ``edit matrix'' is set to ``none''.
This also occurs if the ``edit matrix'' is removed or killed by
another command.

\cmd {edit} {\parm {skew symmetric matrix} skew}

This version of the \icmd{edit} command tells the system that the
specified matrix is a skew-symmetric matrix and that every row
operation \icmd{ar}, \icmd{mr}, and \icmd{pr}  should also be done on
columns in order for the result to remain skew symmetric.

\cmd {ac} {\parm {col c} \parm {polynomial f} \parm {column to modify d}}

Add a polynomial multiple of one column to another column.  Modify the
$d$ th column of the edit matrix by multiplying the $c$ th column of
the edit matrix by $f$, and adding this to the $d$ th column.  $c$ and
$d$ are integer expressions, and $f$ is any polynomial expression in
the base ring of the edit matrix.

\cmd {ar} {\parm {row r} \parm {polynomial f} \parm {row to modify s}}

Add a polynomial multiple of one row to another row.  This command is the
same as \icmd{ac}, but acts on rows rather than columns.

\cmd {ce} {\parm {i} \parm {j} \parm {polynomial f}}

Change the $(i,j)$ entry of the edit matrix to $f$.  $i$ and $j$ are 
integer expressions and $f$ is a polynomial expression in the base
ring of the edit matrix.

This command does not modify the row or column degrees, so it may be
necessary to use either \icmd{setdegs} or \icmd{setcoldegs} to correct
the degrees.

\cmd {mc} {\parm {column c} \parm {polynomial f}}

Multiply the specified column of the edit matrix by the specified polynomial.
$c$ is any integer expression, and $f$ is a polynomial expression in the
base ring of the edit matrix.
	
\cmd {mr} {\parm {row r} \parm {polynomial f}}

Multiply the specified row of the edit matrix by the specified polynomial.
$r$ is any integer expression, and $f$ is a polynomial expression in the
base ring of the edit matrix.

\cmd {pc} {\parm {column i} \parm {column j}}

Permute (interchange) the specified columns of the edit matrix.  $i$ and $j$
are any integer expressions.

\cmd {pr} {\parm {row i} \parm {row j}}

Permute (interchange) the specified rows of the edit matrix.  $i$ and $j$
are any integer expressions.


\section{Graded Matrices and Homogeniety}
\label{sec-mgraded}

Each matrix in \Macaulay\ is presumed to be graded.  i.e. each row and
each column is given an integer degree, and the sum of the $i$ th row
degree with the degree of the $(i,j)$ entry of the matrix is equal to
the $j$ th column degree.

When a matrix is created, its row degrees are all set to zero.  The
degree of each non-zero column is then computed, and every zero column
is given degree zero.

The commands \icmd{setdegs}, \icmd{setcoldegs}, and \icmd{dshift} modify
the row and column degrees of a matrix. This is sometimes necessary
because certain commands do not usually reset the degrees of the matrix
which they modify.  These commands include the ``edit matrix'' commands 
(\secref{sec-medit}), \icmd{concat}, and \icmd{edit-map}.

Most commands of \Macaulay\ will operate on matrices which are not 
graded.  The only commands which require graded matrices are the
commands which compute standard (Groebner) bases.  These commands include
\icmd{std}, \icmd{res}, \icmd{nres}, \icmd{syz}, \icmd{intersect}, 
\icmd{quotient}, \icmd{modulo}, and \icmd{lift-std}.

\cmd {col-degree} {\parm {matrix} \parm {column} \optparm {result integer}}

Set the result integer variable, if given, to the degree of the given
column of the given matrix.  If an integer is not specified, display
this degree.  The \parm{column} is any integer expression.  Zero is
returned if \parm{column} is out of range.

\cmd {col-degs} {\parm{matrix} \optparm{column degrees}}

Display the column degrees of a matrix.  If a second argument is
given, it should be an identifier.  In this case, its value is set to
an n by 0 matrix whose row degrees are the same as the column degrees
of \parm{matrix}.

\cmd {dshift} {\parm{matrix} \parm{degree d to shift by}}

Add the value of the integer expression "d" to each row and column
degree of \parm{matrix}.

\cmd {max} {\parm {matrix} \optparm {result maximum row degree}}

Set the result integer variable, if given, to the maximum row degree
of the given matrix.  If a variable is not specified, display the
maximum degree.  If \parm{matrix} has zero rows, then zero is returned.

\cmd {min} {\parm {matrix} \optparm {result minimum row degree}}

Set the result integer variable, if given, to the minimum row degree
of the given matrix.  If a variable is not specified, display the
minimum degree.  If \parm{matrix} has zero rows, then zero is returned.

\cmd {row-degree} {\parm {matrix} \parm {row} \optparm {result integer}}

Set the result integer variable, if given, to the degree of the given
row of the given matrix.  If a variable is not given, display the
degree.  The \parm{row} is any integer expression.  Zero is returned if the
\parm{row} is out of range.

\cmd {row-degs} {\parm{matrix} \optparm{row degrees}}

Display the row degrees of a matrix.  If a second argument is given,
it should be an identifier.  In this case, its value is set to an n by
0 matrix with the same row degrees as \parm{matrix}.

\cmd {setcoldegs} {\parm{matrix}}

Prompts for the degree of each column.  If \return is typed, the
column degree of each non-zero column is computed from the existing
row degrees.  Each column consisting entirely of zeros has its degree
set to zero.  If instead an integer list is given, this list is used as
the column degrees.  See \secref{sec-intlist} for details on integer
lists.

A warning message is displayed if the resulting matrix is not graded.

\cmd {setdegs} {\parm{matrix}}

Prompts for the row degrees to be assigned to this matrix.  If
\return is typed, every row degree is set to zero.  Otherwise, an
integer list is expected. The system then prompts for the column
degrees.  If \return is typed, the column degree of each non-zero
column is computed from the above row degrees.  Each column consisting
entirely of zeros has its degree set to zero.  If instead an integer
list is given, this list is used as the column degrees.  See
\secref{sec-intlist} for details on integer lists.

A warning message is displayed if the resulting matrix is not graded.



