125 lines
7.6 KiB
TeX
125 lines
7.6 KiB
TeX
\chapter{Introduction}\label{ch:introduction}
|
|
|
|
\section{Purpose}
|
|
|
|
\LA{} is a C++ class library for numerical linear algebra and related tasks.
|
|
Its core are the class templates
|
|
\code{NRVec<T>} (vector), \code{NRMat<T>} (dense matrix) and \code{NRSMat<T>} (symmetric or hermitian
|
|
matrix in packed storage), which provide a convenient and efficient interface to the BLAS and LAPACK
|
|
libraries. Around them a number of further classes and algorithms has grown, mostly motivated by the
|
|
needs of quantum chemistry: sparse matrices, tensors with arbitrary index symmetry, four-index quantities
|
|
(two-electron integrals), iterative eigensolvers and linear solvers working with matrices that are never
|
|
stored explicitly, convergence acceleration, numerical optimization, permutations and the symmetric group,
|
|
polynomials, quaternions and others.
|
|
|
|
The design follows a few principles, which are explained in detail in chapter~\ref{ch:concepts}:
|
|
\begin{itemize}
|
|
\item \emph{Reference counting with copy on demand.} Copying and assigning objects is cheap, data are shared
|
|
until they are modified. Objects can therefore be passed and returned by value. The price is that writing to
|
|
individual elements requires an explicit \code{copyonwrite()} call (section~\ref{sec:concepts:refcount}).
|
|
\item \emph{No expression templates.} The library does not optimize matrix expressions. Operators like
|
|
\code{A*x+y} are available for convenience, but performance critical code should call the BLAS-like member
|
|
functions (\code{gemv}, \code{gemm}, \code{axpy}, \dots) directly, which avoid temporaries.
|
|
\item \emph{Generic algorithms.} Iterative methods (Davidson, Lanczos, conjugate gradients, GMRES, the matrix
|
|
exponential, \dots) are templates which only need a few operations of the matrix class (typically
|
|
\code{nrows()}, \code{ncols()}, \code{diagonalof()} and \code{gemv()}), so that they work with user classes
|
|
which compute the matrix--vector product on the fly (``direct'' methods).
|
|
\item \emph{Nesting.} The element type of the containers can itself be a container, e.g.\
|
|
\code{NRVec<NRMat<double> >}; copy on demand and I/O work recursively (section~\ref{sec:concepts:traits}).
|
|
\end{itemize}
|
|
|
|
The manual is written for users who know both C++ and linear algebra. It explains the concepts and
|
|
gives a compact but complete reference of the public interface. Many further usage examples are in the
|
|
test programs \header{t.cc}, \header{t2.cc} and \header{test.cc} of the distribution; the regression test of the
|
|
optimization module is \header{testoptimize.cc}.
|
|
|
|
The class names \code{NRVec}, \code{NRMat} etc.\ are historical: the classes were first used together with
|
|
the Numerical Recipes library. They can be used with it, but are completely independent of it.
|
|
|
|
\section{Overview}
|
|
|
|
\begin{longtable}{@{}p{0.33\linewidth}p{0.62\linewidth}@{}}
|
|
\toprule
|
|
\textbf{Header} & \textbf{Content} \\
|
|
\midrule
|
|
\endhead
|
|
\header{la.h} & the single include file for the user \\
|
|
\header{vec.h} & \code{NRVec<T>}, \code{NRVec_from1<T>} (chapter~\ref{ch:vec}) \\
|
|
\header{mat.h} & \code{NRMat<T>}, \code{NRMat_from1<T>} (chapter~\ref{ch:mat}) \\
|
|
\header{smat.h} & \code{NRSMat<T>}, \code{NRSMat_from1<T>} (chapter~\ref{ch:smat}) \\
|
|
\header{sparsemat.h}, \header{sparsesmat.h} & sparse matrices \code{SparseMat<T>}, \code{SparseSMat<T>} (chapter~\ref{ch:sparse}) \\
|
|
\header{csrmat.h} & compressed row storage sparse matrix \code{CSRMat<T>} (chapter~\ref{ch:sparse}) \\
|
|
\header{nonclass.h}, \header{matexp.h} & linear systems, eigenvalue problems, SVD, matrix functions (chapter~\ref{ch:nonclass}) \\
|
|
\header{davidson.h}, \header{lanczos.h}, \header{conjgrad.h}, \header{gmres.h}, \header{diis.h}, \header{bisection.h} & iterative methods, DIIS convergence acceleration (chapter~\ref{ch:iterative}) \\
|
|
\header{optimize.h} & numerical optimization (chapter~\ref{ch:optimize}) \\
|
|
\header{tensor.h} & tensors with index symmetries (chapter~\ref{ch:tensor}) \\
|
|
\header{fourindex.h} & four-index quantities, two-electron integrals (chapter~\ref{ch:fourindex}) \\
|
|
\header{permutation.h}, \header{qsort.h} & permutations, partitions, Young tableaux, sorting (chapter~\ref{ch:permutation}) \\
|
|
\header{polynomial.h}, \header{contfrac.h} & polynomials, rationals and continued fractions (chapter~\ref{ch:polynomial}) \\
|
|
\header{vecmat3.h} & 3D vectors and matrices (chapter~\ref{ch:vecmat3}) \\
|
|
\header{quaternion.h} & quaternions (chapter~\ref{ch:quaternion}) \\
|
|
\header{bitvector.h} & bit vectors, polynomials over GF(2) (chapter~\ref{ch:bitvector}) \\
|
|
\header{numbers.h}, \header{graph.h} & number theory, graph algorithms (chapter~\ref{ch:utilities}) \\
|
|
\header{reg.h}, \header{regsurf.h} & regression (chapter~\ref{ch:regression}) \\
|
|
\header{auxstorage.h}, \header{la_random.h}, \header{miscfunc.h}, \header{simple.h}, \header{laerror.h} & utilities (chapter~\ref{ch:utilities}) \\
|
|
\header{la_traits.h} & traits classes, the basis of the generic programming (section~\ref{sec:concepts:traits}) \\
|
|
\bottomrule
|
|
\end{longtable}
|
|
|
|
Everything is declared in the namespace \code{LA}, with the exception of a few headers designed to be usable
|
|
also without the rest of the library (\header{vecmat3.h}: namespace \code{LA_Vecmat3}, \header{quaternion.h}:
|
|
namespace \code{LA_Quaternion}, \header{simple.h}). \header{la.h} includes all headers and contains
|
|
\code{using namespace LA;} together with a few typedefs (\code{NRDVec}, \code{NRCVec}, \code{NRIVec},
|
|
\code{NRDMat}, \code{NRCMat}, \code{NRIMat} for \code{double}, \code{std::complex<double>} and \code{int} elements).
|
|
|
|
\section{A minimal example}
|
|
|
|
\begin{lstlisting}
|
|
#include "la.h"
|
|
using namespace LA;
|
|
using namespace std;
|
|
|
|
int main()
|
|
{
|
|
const int n=4;
|
|
NRSMat<double> h(n);
|
|
h.randomize(1.); //symmetric matrix with random elements
|
|
NRSMat<double> hsave;
|
|
hsave |= h; //deep copy, diagonalize() destroys its argument
|
|
NRVec<double> e(n);
|
|
NRMat<double> v(n,n);
|
|
diagonalize(h,e,&v); //eigenvalues e (ascending), eigenvectors in columns of v
|
|
NRMat<double> r = hsave*v; //residual H V - V diag(e)
|
|
r.copyonwrite(); //always before writing via operator() or []
|
|
for(int i=0; i<n; ++i) for(int j=0; j<n; ++j) r(i,j) -= v(i,j)*e[j];
|
|
cout << e << "residual norm = " << r.norm() << endl;
|
|
}
|
|
\end{lstlisting}
|
|
It is compiled e.g.\ by
|
|
\begin{lstlisting}[language=bash]
|
|
g++ -O3 -I$PREFIX/include example.cc -L$PREFIX/lib -lla -llapack -lcblas -lblas
|
|
\end{lstlisting}
|
|
with the same preprocessor options and libraries the library was configured with
|
|
(chapter~\ref{ch:building}).
|
|
|
|
\section{Conventions used in this manual}
|
|
|
|
\begin{itemize}
|
|
\item \code{T} denotes the element type of a class template. Unless said otherwise, BLAS and LAPACK backed
|
|
operations are available for \code{double} and \code{std::complex<double>}; other element types (integer
|
|
types, nested classes) support the generic operations.
|
|
\item Indices run from 0, unless a \code{_from1} variant of a class is used.
|
|
\item In the reference lists, ``this'' denotes the object the member function is called for.
|
|
Functions that modify the object call \code{copyonwrite()} themselves unless stated otherwise.
|
|
\item Boxes marked \textbf{Caution} point to common pitfalls; yellow boxes are open questions for the
|
|
author, collected in the list at the beginning.
|
|
\end{itemize}
|
|
|
|
\section{Authors and licence}
|
|
|
|
\LA{} is copyright \copyright{} 2008-- Ji\v{r}\'{\i} Pittner. The complex versions of the basic classes were
|
|
written by Roman Curik, the CUDA interface was contributed by Miroslav Sulc; the regression module
|
|
has its own author (chapter~\ref{ch:regression}). The library is free software, distributed under the
|
|
GNU General Public License, version~3 or later.
|
|
Since 2026, the author started to employ an AI assistant for code review, documentation, and some new implementations.
|