# 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:
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_PMRRR
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:

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:


## 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.

## 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 of a process grid; it is used to tune 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
enumerator UNSORTED

Do not sort.

enumerator DESCENDING

Smallest values first.

enumerator ASCENDING

Largest 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_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 and conjugate

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.