Environment

This section describes the routines and data structures which help set up Elemental’s programming environment: it discusses initialization of Elemental, call stack manipulation, a custom data structure for complex data, many routines for manipulating real and complex data, a litany of custom enums, and a few useful routines for simplifying index calculations.

Build and version information

Every Elemental driver with proper command-line argument processing will run PrintVersion if the --version argument is used. If --build is used, then all of the below information is reported.

void PrintVersion(std::ostream &os = std::cout)

Prints the Git revision, (pre-)release version, and build type. For example:

Elemental version information:
  Git revision: 3c6fbdaad901a554fc27a83378d63dab55af0dd3
  Version:      0.81-dev
  Build type:   PureDebug
void PrintConfig(std::ostream &os = std::cout)

Prints the relevant configuration details. For example:

Elemental configuration:
  Math libraries: /usr/lib/liblapack.so;/usr/lib/libblas.so
  HAVE_F90_INTERFACE
  HAVE_MPI_REDUCE_SCATTER_BLOCK
  HAVE_MPI_IN_PLACE
  USE_BYTE_ALLGATHERS
void PrintCCompilerInfo(std::ostream &os = std::cout)

Prints the relevant C compilation information. For example:

Elemental's C compiler info:
  CMAKE_C_COMPILER:    /usr/local/bin/gcc
  MPI_C_COMPILER:      /home/poulson/Install/bin/mpicc
  MPI_C_INCLUDE_PATH:  /home/poulson/Install/include
  MPI_C_COMPILE_FLAGS:
  MPI_C_LINK_FLAGS:     -Wl,-rpath  -Wl,/home/poulson/Install/lib
  MPI_C_LIBRARIES:     /home/poulson/Install/lib/libmpich.so;/home/poulson/Install/lib/libopa.so;/home/poulson/Install/lib/libmpl.so;/usr/lib/i386-linux-gnu/librt.so;/usr/lib/i386-linux-gnu/libpthread.so
void PrintCxxCompilerInfo(std::ostream &os = std::cout)

Prints the relevant C++ compilation information. For example:

Elemental's C++ compiler info:
  CMAKE_CXX_COMPILER:    /usr/local/bin/g++
  CXX_FLAGS:             -Wall
  MPI_CXX_COMPILER:      /home/poulson/Install/bin/mpicxx
  MPI_CXX_INCLUDE_PATH:  /home/poulson/Install/include
  MPI_CXX_COMPILE_FLAGS:
  MPI_CXX_LINK_FLAGS:     -Wl,-rpath  -Wl,/home/poulson/Install/lib
  MPI_CXX_LIBRARIES:     /home/poulson/Install/lib/libmpichcxx.so;/home/poulson/Install/lib/libmpich.so;/home/poulson/Install/lib/libopa.so;/home/poulson/Install/lib/libmpl.so;/usr/lib/i386-linux-gnu/librt.so;/usr/lib/i386-linux-gnu/libpthread.so

Set up and clean up

void Initialize(int &argc, char **&argv)

Initializes Elemental and (if necessary) MPI. The usage is very similar to MPI_Init, but the argc and argv can be directly passed in.

#include "elemental.hpp"
int main( int argc, char* argv[] )
{
    elem::Initialize( argc, argv );
    // ...
    elem::Finalize();
    return 0;
}
void Finalize()

Frees all resources allocated by Elemental and (if necessary) MPI.

bool Initialized()

Returns whether or not Elemental is currently initialized.

void ReportException(std::exception &e)

Used for handling Elemental’s various exceptions, e.g.,

#include "elemental.hpp"
int main( int argc, char* argv[] )
{
    elem::Initialize( argc, argv );
    try {
        // ...
    } catch( std::exception& e ) { ReportException(e); }
    elem::Finalize();
    return 0;
}

Blocksize manipulation

int Blocksize()

Return the currently chosen algorithmic blocksize. The optimal value depends on the problem size, algorithm, and architecture; the default value is 128.

void SetBlocksize(int blocksize)

Change the algorithmic blocksize to the specified value.

void PushBlocksizeStack(int blocksize)

It is frequently useful to temporarily change the algorithmic blocksize, so rather than having to manually store and reset the current state, one can simply push a new value onto a stack (and later pop the stack to reset the value).

void PopBlocksizeStack()

Pops the stack of blocksizes. See above.

int DefaultBlockHeight()
int DefaultBlockWidth()

Returns the default block height (width) for BlockDistMatrix<T,U,V>.

void SetDefaultBlockHeight(int mb)
void SetDefaultBlockWidth(int nb)

Change the default block height (width) for BlockDistMatrix<T,U,V>.

Default process grid

Grid &DefaultGrid()

Return a process grid built over mpi::COMM_WORLD. This is typically used as a means of allowing instances of the DistMatrix<T,MC,MR> class to be constructed without having to manually specify a process grid, e.g.,

// Build a 10 x 10 distributed matrix over mpi::COMM_WORLD
elem::DistMatrix<T,MC,MR> A( 10, 10 );

Call stack manipulation

Note

The following call stack manipulation routines are only available in non-release builds (i.e., PureDebug and HybridDebug) and are meant to allow for the call stack to be printed (via DumpCallStack()) when an exception is caught.

void PushCallStack(std::string s)

Push the given routine name onto the call stack.

void PopCallStack()

Remove the routine name at the top of the call stack.

void DumpCallStack()

Print (and empty) the contents of the call stack.

Custom exceptions

class SingularMatrixException

An extension of std::runtime_error which is meant to be thrown when a singular matrix is unexpectedly encountered.

SingularMatrixException(const char *msg = "Matrix was singular")

Builds an instance of the exception which allows one to optionally specify the error message.

throw elem::SingularMatrixException();
class NonHPDMatrixException

An extension of std::runtime_error which is meant to be thrown when a non positive-definite Hermitian matrix is unexpectedly encountered (e.g., during Cholesky factorization).

NonHPDMatrixException(const char *msg = "Matrix was not HPD")

Builds an instance of the exception which allows one to optionally specify the error message.

throw elem::NonHPDMatrixException();
class NonHPSDMatrixException

An extension of std::runtime_error which is meant to be thrown when a non positive semi-definite Hermitian matrix is unexpectedly encountered (e.g., during computation of the square root of a Hermitian matrix).

NonHPSDMatrixException(const char *msg = "Matrix was not HPSD")

Builds an instance of the exception which allows one to optionally specify the error message.

throw elem::NonHPSDMatrixException();

Complex data

template<>
type Complex<Real>

Currently a typedef of std::complex<Real>

template<>
type Base<F>

The underlying real datatype of the (potentially complex) datatype F. For example, Base<Complex<double>> and Base<double> are both equivalent to double. This is often extremely useful in implementing routines which are templated over real and complex datatypes but still make use of real datatypes.

std::ostream &operator<<(std::ostream &os, Complex<Real> alpha)

Pretty prints alpha in the form a+bi.

type scomplex

typedef Complex<float> scomplex;

type dcomplex

typedef Complex<double> dcomplex;

Scalar manipulation

Base<F> Abs(const F &alpha)

Return the absolute value of the real or complex variable \(\alpha\).

F FastAbs(const F &alpha)

Return a cheaper norm of the real or complex \(\alpha\):

\[|\alpha|_{\mbox{fast}} = |\mathcal{R}(\alpha)| + |\mathcal{I}(\alpha)|\]
F RealPart(const F &alpha)
F ImagPart(const F &alpha)

Return the real (imaginary) part of the real or complex variable \(\alpha\).

void SetRealPart(F &alpha, Base<F> &beta)
void SetImagPart(F &alpha, Base<F> &beta)

Set the real (imaginary) part of the real or complex variable \(\alpha\) to \(\beta\). If \(\alpha\) has a real type, an error is thrown when an attempt is made to set the imaginary component.

void UpdateRealPart(F &alpha, Base<F> &beta)
void UpdateImagPart(F &alpha, Base<F> &beta)

Update the real (imaginary) part of the real or complex variable \(\alpha\) to \(\beta\). If \(\alpha\) has a real type, an error is thrown when an attempt is made to update the imaginary component.

F Conj(const F &alpha)

Return the complex conjugate of the real or complex variable \(\alpha\).

F Sqrt(const F &alpha)

Returns the square root or the real or complex variable \(\alpha\).

F Cos(const F &alpha)

Returns the cosine of the real or complex variable \(\alpha\).

F Sin(const F &alpha)

Returns the sine of the real or complex variable \(\alpha\).

F Tan(const F &alpha)

Returns the tangent of the real or complex variable \(\alpha\).

F Cosh(const F &alpha)

Returns the hyperbolic cosine of the real or complex variable \(\alpha\).

F Sinh(const F &alpha)

Returns the hyperbolic sine of the real or complex variable \(\alpha\).

Base<F> Arg(const F &alpha)

Returns the argument of the real or complex variable \(\alpha\).

Complex<Real> Polar(const R &r, const R &theta = 0)

Returns the complex variable constructed from the polar coordinates \((r,\theta)\).

F Exp(const F &alpha)

Returns the exponential of the real or complex variable \(\alpha\).

F Pow(const F &alpha, const F &beta)

Returns \(\alpha^\beta\) for real or complex \(\alpha\) and \(\beta\).

F Log(const F &alpha)

Returns the logarithm of the real or complex variable \(\alpha\).

Other typedefs and enums

type byte

typedef unsigned char byte;

enum Conjugation
enumerator CONJUGATED
enumerator UNCONJUGATED
enum Distribution

For specifying the distribution of a row or column of a distributed matrix:

enumerator MC

Column of a standard matrix distribution

enumerator MD

Diagonal of a standard matrix distribution

enumerator MR

Row of a standard matrix distribution

enumerator VC

Column-major vector distribution

enumerator VR

Row-major vector distribution

enumerator STAR

Redundantly stored on every process

enumerator CIRC

Stored on a single process

enum ForwardOrBackward
enumerator FORWARD
enumerator BACKWARD
enum GridOrder

For specifying either a ROW_MAJOR or COLUMN_MAJOR ordering; it is used to decide how to construct process grids and is also useful for tuning one of the algorithms in HermitianTridiag() which requires building a smaller square process grid from a rectangular process grid, as the ordering of the processes can greatly impact performance. See SetHermitianTridiagGridOrder().

enumerator ROW_MAJOR
enumerator COLUMN_MAJOR
enum LeftOrRight
enumerator LEFT
enumerator RIGHT
enum SortType

For specifying a sorting strategy:

enumerator UNSORTED

Do not sort

enumerator DESCENDING

Largest values first

enumerator ASCENDING

Smallest values first

enum NormType
enumerator ONE_NORM
\[\|A\|_1 = \max_{\|x\|_1=1} \|Ax\|_1 = \max_j \sum_{i=0}^{m-1} |\alpha_{i,j}|\]
enumerator INFINITY_NORM
\[\|A\|_{\infty} = \max_{\|x\|_{\infty}=1} \|Ax\|_{\infty} = \max_i \sum_{j=0}^{n-1} |\alpha_{i,j}|\]
enumerator ENTRYWISE_ONE_NORM
\[\|\text{vec}(A)\|_1 = \sum_{i,j} |\alpha_{i,j}|\]
enumerator MAX_NORM
\[\|A\|_{\mbox{max}} = \max_{i,j} |\alpha_{i,j}|\]
enumerator NUCLEAR_NORM
\[\|A\|_* = \sum_{i=0}^{\min(m,n)} \sigma_i(A)\]
enumerator FROBENIUS_NORM
\[\|A\|_F = \sqrt{\sum_{i=0}^{m-1} \sum_{j=0}^{n-1} |\alpha_{i,j}|^2} = \sum_{i=0}^{\min(m,n)} \sigma_i(A)^2\]
enumerator TWO_NORM
\[\|A\|_2 = \max_i \sigma_i(A)\]
enum Orientation
enumerator NORMAL

Do not transpose or conjugate

enumerator TRANSPOSE

Transpose without conjugation

enumerator ADJOINT

Transpose with conjugation

enum UnitOrNonUnit
enumerator UNIT
enumerator NON_UNIT
enum UpperOrLower
enumerator LOWER
enumerator UPPER
enum VerticalOrHorizontal
enumerator VERTICAL
enumerator HORIZONTAL

Indexing utilities

int Shift(int rank, int firstRank, int numProcs)

Given a element-wise cyclic distribution over numProcs processes, where the first entry is owned by the process with rank firstRank, this routine returns the first entry owned by the process with rank rank.

int Length(int n, int shift, int numProcs)

Given a vector with \(n\) entries distributed over numProcs processes with shift as defined above, this routine returns the number of entries of the vector which are owned by this process.

int Length(int n, int rank, int firstRank, int numProcs)

Given a vector with \(n\) entries distributed over numProcs processes, with the first entry owned by process firstRank, this routine returns the number of entries locally owned by the process with rank rank.

int MaxLength(int n, int numProcs)

The maximum result of Length() with the given parameters. This is useful for padding collective communication routines which are almost regular.

int Mod(int a, int b)

An extension of C++’s % operator which handles cases where a is negative and still returns a result in \([0,b)\).

int GCD(int a, int b)

Return the greatest common denominator of the integers a and b.

unsigned Log2(unsigned n)

Return the base-two logarithm of a positive integer.

bool PowerOfTwo(unsigned n)

Return whether or not a positive integer is an integer power of two.