# API¶

class abcd
Public Functions
int operator()(int job_id)

The gateway function that launches all other options

 Run an operation identified by the value of job_id, it can be
either:
- -1, initializes the internal matrix used by the
solver. Prior to this call, the user must provide:
* The information about the matrix. #m, #n, #nz,
#sym, #irn, #jcn and #val have to be initialized before the
call.
* After the call, the arrays #irn, #jcn and #val
are no longer used by the solver and can be freely deallocated.
- 1, performs the preprocessing. During this call, the solver
scales the matrix, partitions it and, if requested by the user,
performs the augmentation of the matrix. Prior to this call, the
user must provide:

* The number of partitions to create (see nbparts )
or ask the solver to guess the appropriate number of
partitions (see part_guess)
* The type of scaling to perform (see scaling)
* The type of augmentation to perform (see aug_type)
- 2, creates the augmented systems, analyses them, creates
the mapping between the different mpi-processes and
factorizes the augmented systems.
- 3, performs the solution step, the right-hand sides and
their number are required prior to this call.
* The right-hand sides have to be given through the array
rhs[] and their number in #nrhs.
* The block-size to be used during the block-CG
acceleration. Its value is used only during the regular
block Cimmino solve, and by default its value is 1.
* The solution is centralized (on the master) in the array
sol[].
- 4, combines the call to the phases 1 and 2.
- 5, combines the call to the phases 2 and 3.
- 6, combines the call to the phases 1, 2 and 3.


int initializeMatrix()

Creates the internal matrix from user’s data.

int preprocessMatrix()

Scales, partitions and analyses the structure of partitions.

int factorizeAugmentedSystems()

Creates augmented systems and factorizes them.

int solveSystem()

Runs either BCG or ABCD solve depending on what we want.

abcd()

Set the defaults in the constructor.

Public Members
int m

The number of rows in the matrix

int n

The number of columns in the matrix

int nz

The number of entries in the matrix

bool sym

The symmetry of the matrix

int * irn

The row indices of size nz

int * jcn

The column indices of size nz

int start_index

Defines wether it’s Fortran-Style (1) or C-Style (0, default)

double * val

The entries of the matrix of size nz

int nrhs

The number of right-hand sides to solve, default is 1

double * rhs

The right-hand side of size m * nrhs

double * sol

The solution vector of size n * nrhs

std::vector< int > icntl

The integer control array, see Controls::icontrols for the possible values

std::vector< double > dcntl

The real control array, see Controls::dcontrols for the possible values

std::vector< int > info

The integer info output array, see Controls::info

std::vector< double > dinfo

The real info output array, see Controls::dinfo

std::string write_problem

The path where to write the matrix $$PD_rAD_cP^T$$

std::string write_s

The path where to write the matrix $$S_k$$ where $$k$$ is the mpi-process rank

std::string log_output

The file where to write logging information

std::vector< int > strow

The starting row index of each partition

std::vector< int > nbrows

The number of rows per partition

mpi::communicator comm

The global communicator

int parallel_cg

The number of parallel CG instances

namespace Controls

Defines the control parameters indices in a safe way.

Enums
icontrols enum

To be used with the abcd::icntl vector.

Values:

• nbparts -

Number of partitions.

Defines the number of partitions in our linear system, can be from 1 to m (the number of rows in the matrix)

// we have 8 partitions
obj.icntl[nbparts] = 8;


• part_type -

Partitioning strategy.

Defines the partitioning strategy, it can have the values:

• 1, Manual partitioning, the nbparts partitions can be provided in the STL vector nbrows. Example:
// use manual partitioning
obj.icntl[part_type] = 1;
// say that we want 20 rows per partition
obj.nrows.assign(obj.icntl[nbparts], 20);

// or
obj.nrows.resize(obj.icntl[nbparts]);
obj.nrows[0] = 20;
obj.nrows[1] = 20;
//...


For C, the nrows vector is an int array:

// use manual partitioning
obj->icntl[part_type] = 1;

obj->nrows =  (int*) malloc(sizeof(int)*(obj->icntl[nbparts]));

obj->nrows[0] = 20;
obj->nrows[1] = 20;
//...


• 2, (default) Automatic uniform partitioning, creates nbparts partitions of similar size.
// use patoh partitioning
obj.icntl[part_type] = 2;


• 3, Automatic hypergraph partitioning, creates nbparts partitions using the hypergraph partitioner PaToH. The imbalance between the partitions is handled using obj.dcntl[part_imbalance]. Example:
// use patoh partitioning
obj.icntl[part_type] = 3;
// say that we want an imbalance factor up to 30% between the partitions
obj.dcntl[part_imbalance] = 0.3;


• part_guess -

Guess the number of partitions.

Asks the solver to guess the appropriate number of partitions and overrides the defined nbparts.

• 0 (default), The user has to provide the number of partitions by setting icntl[nbparts]
• 1, Guess the number of partitions by trying to create a small number of partitions while keeping them small enough to be handled easily by the direct solver

• scaling -

The scaling type.

Defines the type of scaling to be used.

• 0, no scaling
• 1, scale the input matrix (embeded internal scaling strategy)

• itmax -

The max number of iterations.

Defines the maximum number of iterations in block-CG acceleration, default is 1000 iterations.

• block_size -

Block-CG block-size.

Defines the block-size to be used by the block-CG acceleration, default is 1 for classical CG acceleration. When using a higher value than 1, stabilized Block-CG is used.

• verbose_level -

The verbose level.

Defines the verbosity of the solver

• aug_type -

The augmentation type.

Possible values are:

• 0 (default), no augmentation. This makes the solver run in regular block Cimmino mode.

• 1, makes the solver run in Augmented Block Cimmino mode with an augmentation of the matrix using the $$C_{ij}$$ augmentation strategy. For numerical stability, this augmentation technique has to be used with a scaling.

• 2, makes the solver run in Augmented Block Cimmino mode with an augmentation of the matrix using the $$A_{ij}$$ augmentation starategy.

• aug_blocking -

The blocking factor in ABCD.

Defines the blocking factor used by the solver during the solution phase, its default value is 128. This allows the solver to take advantage of BLAS3 Kernels. The optimal value is hardware and problem size related. The user has also to find a compromise between memory and computing time.

dcontrols enum

Values:

• part_imbalance -

The imbalance factor in PaToH case.

• threshold -

The stoping threshold.

info enum

Values:

• status -

Exit status.

• nb_iter -

Number of iterations after CG.

dinfo enum

Values:

• residual -

The resulting residual.

• forward_error -

The resulting forward error.

• backward -

The resulting residual.

• scaled_residual -

The resulting residual.