Index: ThirdParty/mpqc_open/src/lib/math/scmat/scmat.dox
===================================================================
--- ThirdParty/mpqc_open/src/lib/math/scmat/scmat.dox	(revision 860145ede0311b3539e419277d8ca4a3091f40b2)
+++ ThirdParty/mpqc_open/src/lib/math/scmat/scmat.dox	(revision 860145ede0311b3539e419277d8ca4a3091f40b2)
@@ -0,0 +1,284 @@
+
+/** \page scmat The Matrix Library
+
+The scientific computing matrix library (SCMAT) is designed around a set of
+matrix abstractions that permit very general matrix implementations.  This
+flexibility is needed to support diverse computing environments.  For
+example, this library must support, at a minimum: simple matrices that
+provide efficient matrix computations in a uniprocessor environment,
+clusters of processors with enough memory to store all matrices connected
+by a relatively slow network (workstations on an LAN), clusters of
+processors with enough memory to store all matrices and a fast interconnect
+network (a massively parallel machine such as the Intel Paragon), and
+clusters of machines that don't have enough memory to hold entire matrices.
+
+<ul>
+  <li> \ref scmatover
+  <li> \ref scmatdim
+  <li> \ref scmatref
+  <li> \ref scmatabstract
+  <li> \ref scmatstor
+  <li> \ref scmatop
+  <li> \ref scmatopsp
+  <li> \ref scmatlocal
+  <li> \ref scmatrepl
+  <li> \ref scmatdist
+  <li> \ref scmatblocked
+</ul>
+
+\section scmatover Overview
+
+The design of SCMAT differs from other object-oriented matrix packages in
+two important ways.  First, the matrix classes are abstract base classes.
+No storage layout is defined and virtual function calls must be used to
+access individual matrix elements.  This would have a negative performance
+impact if users needed to frequently access matrix elements.  The interface
+to the matrix classes is hopefully rich enough to avoid individual matrix
+element access for any computationally significant task.  The second major
+difference is that symmetric matrices do not inherit from matrices, etc.
+The SCMAT user must know whether a matrix is symmetric at all places it is
+used if any performance gain, by virtue of symmetry, is expected.
+
+Dimension information is contained objects of the SCDimension type.  In
+addition to the simple integer dimension, application specific blocking
+information can be provided.  For example, in a quantum chemistry
+application, the dimension corresponding to the atomic orbital basis set
+will have block sizes that correspond to the shells.  Dimensions are used
+to create new matrix or vector objects.
+
+The primary abstract classes are SCMatrix, SymmSCMatrix, DiagSCMatrix, and
+SCVector.  These represent matrices, symmetric matrices, diagonal matrices,
+and vectors, respectively.  These abstract classes are specialized into
+groups of classes.  For example, the locally stored matrix implementation
+specializes the abstract classes to LocalSCMatrix, LocalSymmSCMatrix,
+LocalDiagSCMatrix, LocalSCVector, LocalSCDimension, and LocalSCMatrixKit.
+These specializations are all designed to work with each other.  However, a
+given specialization is incompatible with other matrix specializations.  An
+attempt to multiply a local matrix by a distributed matrix would generate
+an error at runtime.
+
+Since the different groups of classes do not interoperate, some mechanism
+of creating consistent specializations is needed.  This is done with
+SCMatrixKit objects.  SCMatrixKit is an abstract base type which has
+specializations that correspond to each group of the matrix
+specializations.  It is used to create matrices and vectors from that
+group.  For example, the DistSCMatrixKit is used to create objects of type
+DistSCMatrix, DistSymmSCMatrix, DistDiagSCMatrix, and DistSCVector.
+
+The abstract matrix classes and their derivations are usually not directly
+used by SCMAT users.  The most convenient classes to use are the smart
+pointer classes RefSCMatrix, RefSymmSCMatrix, RefDiagSCMatrix,
+and RefSCDimension.
+These classes respectively inherit from Ref<SCMatrix>, Ref<SymmSCMatrix>,
+Ref<DiagSCMatrix>, and Ref<SCDimension>, providing automatic memory
+management through reference counting.
+The smart pointer classes also have matrix
+operations such as operator *(), operator -(), and operator +() defined as
+members for convenience.  These forward the operations to the contained
+matrix object.  The smart pointer classes also simplify creation of
+matrices by providing constructors that take as arguments one or more
+RefSCDimension's and a Ref<SCMatrixKit>.  These initialize the smart pointer
+to contain a new matrix with a specialization corresponding to that of the
+Ref<SCMatrixKit>.  Matrix operations not provided by the smart pointer
+classes but present as member in the abstract classes can be accessed with
+operator->().
+
+If a needed matrix operation is missing, mechanisms exist to add more
+general operations.  Operations which only depend on individual elements of
+matrices can be provided by specializations of the SCElementOp class.
+Sometimes we need operations on matrices with identical dimensions that
+examine each element in one matrix along with the corresponding element
+from the other matrix.  This is accomplished with SCElementOp2 for two
+matrices and with SCElementOp3 for three.
+
+Other features of SCMAT include run-time type facilities and persistence.
+Castdown operations (type conversions from less to more derived objects)
+and other run-time type information are provided by the DescribedClass base
+class.  Persistence is not provided by inheriting from SavableState base
+clase as is the case with many other classes in the SC class hierarchies,
+because it is necessary to save objects in an implementation independent
+manner.  If a calculation checkpoints a matrix on a single processor
+machine and later is restarted on a multiprocessor machine the matrix would
+need to be restored as a different matrix specialization.  This is handled
+by saving and restoring matrices' and vectors' data without reference to
+the specialization.
+
+The following include files are provided by the matrix library:
+
+<dl>
+<dt><tt>matrix.h</tt><dd>
+Usually, this is the only include file needed by users of matrices.  It
+declares reference counting pointers to abstract matrices.
+
+If kit for a matrix must be created, or a member specific to an
+implementation is needed, then that implementation's header file must be
+included.
+
+<dt><tt>elemop.h</tt><dd>
+This is the next most useful include file.  It defines useful
+SCElementOp, SCElementOp2, and SCElementOp3
+specializations.
+
+<dt><tt>abstract.h</tt><dd>
+This include file contains the declarations for abstract classes that
+users do not usually need to see.  These include SCDimension,
+SCMatrix, SymmSCMatrix, DiagSCMatrix,
+SCMatrixKit.  This file is currently included by
+matrix.h.
+
+<dt><tt>block.h</tt><dd>
+This file declares SCMatrixBlock and specializations.  It
+only need be include by users implementing new SCElementOp
+specializations.
+
+<dt><tt>blkiter.h</tt><dd>
+This include file declares the implementations of
+SCMatrixBlockIter.  It only need be include by users implementing
+new SCElementOp specializations.
+
+<dt><tt>vector3.h</tt><dd>
+This declares SCVector3, a lightweight vector of length three.
+
+<dt><tt>matrix3.h</tt><dd>
+This declares SCMatrix3, a lightweight matrix of dimension three by
+three.  It includes vector3.h.
+
+<dt><tt>local.h</tt><dd>
+This include file is the matrix implementation for locally stored
+matrices.  These are suitable for use in a uniprocessor environment.  The
+LocalSCMatrixKit is the default matrix implementation returned
+by the static member SCMatrixKit::default_matrixkit.
+This file usually doesn't need to be included.
+
+<dt><tt>dist.h</tt><dd>
+This include file is the matrix implementation for distributed matrices.
+These are suitable for use in a distributed memory multiprocessor which
+does not have enough memory to hold all of the matrix elements on each
+processor.  This file usually doesn't need to be included.
+
+<dt><tt>repl.h</tt><dd>
+This include file is the matrix implementation for replicated matrices.
+These are suitable for use in a distributed memory multiprocessor which
+does have enough memory to hold all of the matrix elements on each
+processor.  This file usually doesn't need to be included.
+
+<dt><tt>blocked.h</tt><dd>
+This include file is the matrix implementation for blocked matrices.
+Blocked matrices store a matrix as subblocks that are matrices from another
+matrix specialization.  These are used to save storage and computation time
+in quantum chemistry applications for molecules with other than \f$C_1\f$ point
+group symmetry.
+
+</dl>
+
+\section scmatdim Matrix Dimensions
+
+In addition to the simple integer dimension, objects of the SCDimension
+class contain application specific blocking information.  This information
+is held in an object of class SCBlockInfo.
+
+\section scmatref Matrix Reference Classes
+
+The easiest way to use SCMAT is through the smart pointer classes
+RefSCMatrix, RefSymmSCMatrix, RefDiagSCMatrix, RefSCVector, RefSCDimension,
+and Ref<SCMatrixKit>.  These are based on the Ref reference counting package
+and automatically delete matrix objects when they are no longer needed.
+These reference classes also have common operations defined as members for
+convenience.  This makes it unnecessary to also use the sometimes awkward
+syntax of operator->() to manipulate the contained objects.
+
+\section scmatabstract Abstract Matrix Classes
+
+This section documents the primary abstract classes: SCMatrix,
+SymmSCMatrix, DiagSCMatrix, and SCVector, as well as the SCMatrixKit class
+which allows the programmer to generate consistent specializations of
+matrices.  These represent matrices, symmetric matrices, diagonal matrices,
+and vectors, respectively.
+
+This section is primarily for implementers of new specializations
+of matrices.  Users of existing matrices will be most interested
+in the matrix reference classes.
+
+\section scmatstor Matrix Storage
+
+All elements of matrices and vectors are kept in blocks.  The
+choice of blocks and where they are keep is left up to each
+matrix specialization.
+
+\section scmatop Manipulating Matrix Elements with Element Operations
+
+The SCElementOp, SCElementOp2, and SCElementOp3 classes can
+be used to maniupulate matrix elements.
+
+\section scmatopsp SCElementOp Specializations
+
+Several commonly needed element operations are already coded up and
+available by including math/scmat/elemop.h.  Below are descriptions
+of these classes:
+
+<dl>
+<dt>SCElementScalarProduct<dd> This SCElementOp2 computes
+the scalar product of two matrices or vectors.  The result is available
+after the operation from the return value of the result() member.
+<dt>SCDestructiveElementProduct<dd> This SCElementOp2
+replaces the elements of the matrix or vector whose element_op
+member is called.  The resulting values are the element by element products
+of the two matrices or vectors.
+<dt>SCElementScale<dd> This scales each element by an amount given
+in the constructor.
+<dt>SCElementRandomize<dd> This generates random elements.
+<dt>SCElementAssign<dd> Assign to each element the value passed to
+the constructor.
+<dt>SCElementSquareRoot<dd> Replace each element with its square
+root.
+<dt>SCElementInvert<dd> Replace each element by its reciprocal.
+<dt>SCElementScaleDiagonal<dd> Scales the diagonal elements of a
+matrix by the argument passed to the constructor.  Use of this on a vector
+is undefined.
+<dt>SCElementShiftDiagonal<dd> Add the value passed to the
+constructor to the diagonal elements of the matrix.  Use of this on a
+vector is undefined.
+<dt>SCElementMaxAbs<dd> Find the maximum absolute value element in a
+matrix or vector.  The result is available as the return value of the
+<tt>result()</tt> member.
+<dt>SCElementDot<dd> The constructor for this class takes three
+arguments: SCElementDot(double**a,
+double**b, int length).  The length of each vector given by
+a and b is given by length.  The number of vectors in
+a is the number of rows in the matrix and the number in b is
+the number of columns.  To each element in the matrix \f$m_{ij}\f$ the dot
+product of the \f$a_i\f$ and \f$b_j\f$ is added.
+<dt>SCElementAccumulateSCMatrix<dd>  This is obsolete---do not use it.
+<dt>SCElementAccumulateSymmSCMatrix<dd> This is obsolete---do not
+use it.
+<dt>SCElementAccumulateDiagSCMatrix<dd> This is obsolete---do not
+use it.
+<dt>SCElementAccumulateSCVector<dd> This is obsolete---do not use
+it.
+</dl>
+
+\section scmatlocal Local Matrices
+
+Local matrices do no communication.  All elements reside on each node
+and all computations are duplicated on each node.
+
+\section scmatrepl Replicated Matrices
+
+Replicated matrices hold all of the elements on each node, however
+do some communications in order to reduce computation time.
+
+\section scmatdist Distributed Matrices
+
+Distributed matrices spread the elements across all the nodes and
+thus require less storage than local matrices however these use
+more communications than replicated matrices.
+
+\section scmatblocked Blocked Matrices
+
+Blocked matrices are used to implement point group symmetry.  Another
+matrix specialization is used to hold the diagonal subblocks of a
+matrix.  The offdiagonal subblocks are known to be zero and not stored.
+This results in considerable savings in storage and computation for
+those cases where it applies.
+
+*/
