\HeaderA{Diagonal}{Create Diagonal Matrix Object}{Diagonal}
\aliasA{.symDiagonal}{Diagonal}{.symDiagonal}
\keyword{array}{Diagonal}
\keyword{algebra}{Diagonal}
\begin{Description}\relax
Create a diagonal matrix object, i.e., an object inheriting from
\code{\LinkA{diagonalMatrix}{diagonalMatrix.Rdash.class}}.
\end{Description}
\begin{Usage}
\begin{verbatim}
Diagonal(n, x = NULL)
.symDiagonal(n, x = rep.int(1,n), uplo = "U")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{n}] integer specifying the dimension of the (square) matrix.  If
missing, \code{length(x)} is used.
\item[\code{x}] numeric or logical; if missing, a \emph{unit} diagonal
\eqn{n \times n}{} matrix is created.
\item[\code{uplo}] for \code{.symDiagonal}, the resulting sparse
\code{\LinkA{symmetricMatrix}{symmetricMatrix.Rdash.class}} will have slot \code{uplo} set
from this argument, either \code{"U"} or \code{"L"}.  Only rarely
will it make sense to change this from the default.
\end{ldescription}
\end{Arguments}
\begin{Value}
\code{Diagonal()} returns an object of class
\code{\LinkA{ddiMatrix}{ddiMatrix.Rdash.class}} or \code{\LinkA{ldiMatrix}{ldiMatrix.Rdash.class}}
(with \dQuote{superclass} \code{\LinkA{diagonalMatrix}{diagonalMatrix.Rdash.class}}).

\code{.symDiagonal()} returns an object of class
\code{\LinkA{dsCMatrix}{dsCMatrix.Rdash.class}} or \code{\LinkA{lsCMatrix}{lsCMatrix.Rdash.class}},
i.e., a \emph{sparse} \emph{symmetric} matrix.  This can be
more efficient than \code{Diagonal(n)} when the result is combined
with further symmetric (sparse) matrices, however \emph{not} for
matrix multiplications where \code{Diagonal()} is clearly preferred.
\end{Value}
\begin{SeeAlso}\relax
the generic function \code{\LinkA{diag}{diag}} for \emph{extraction}
of the diagonal from a matrix works for all \dQuote{Matrices}.

\code{\LinkA{bandSparse}{bandSparse}} constructs a \emph{banded} sparse matrix from
its non-zero sub-/super - diagonals.

\code{\LinkA{Matrix}{Matrix}} for general matrix construction;
further, class \code{\LinkA{diagonalMatrix}{diagonalMatrix.Rdash.class}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
Diagonal(3)
Diagonal(x = 10^(3:1))
Diagonal(x = (1:4) >= 2)#-> "ldiMatrix"

## Use Diagonal() + kronecker() for "repeated-block" matrices:
M1 <- Matrix(0+0:5, 2,3)
(M <- kronecker(Diagonal(3), M1))

(S <- crossprod(Matrix(rbinom(60, size=1, prob=0.1), 10,6)))
(SI <- S + 10*.symDiagonal(6)) # sparse symmetric still
stopifnot(is(SI, "dsCMatrix"))
\end{ExampleCode}
\end{Examples}

