Usage

The library is presented as a single load balancing object ALL::ALL from ALL.hpp. All classes are encapsulated in the ALL name space. Simple (and not so simple) examples are available in the /examples sub directory. The simple examples are also documented at length. In cases where the name ALL is misleading, the library is referred to as libALL.

Errors are treated as exceptions that are thrown of a (sub) class of ALL::CustomException. Likely candidates that may throw exceptions are balance,``setup``, printVTKoutlines.

ALL object

The ALL object can be constructed with

ALL::ALL<T,W> (
               const ALL::LB_t method,
               const int dimension,
               const T gamma)

Where the type of the boundaries is given by T and the type of the work as W, which are usually float or double. The load balancing method must be one of ALL::LB_t::TENSOR, ...STAGGERED, ...FORCEBASED, ...VORONOI, ...HISTOGRAM. Where the Voronoi method must be enabled at compile time. There is also a second form where the initial domain vertices are already provided:

ALL::ALL<T,W> (
               const ALL::LB_t method,
               const int dimension,
               const std::vector<ALL::Point<T>> &initialDomain,
               const T gamma)

Point object

The domain boundaries are given and retrieved as a vector of ALL::Point s. These can be constructed via

ALL::Point<T> ( const int dimension )
ALL::Point<T> ( const int dimension, const T *values )
ALL::Point<T> ( const std::vector<T> &values )

and its elements can be accessed through the [] operator like a std::vector.

Set up

A few additional parameters must be set before the domains can be balanced. Which exactly need to be set, is dependent on the method used, but in general the following are necessary

void ALL::ALL<T,W>::setVertices ( std::vector<ALL::Point<T>> &vertices )
void ALL::ALL<T,W>::setCommunicator ( MPI_Comm comm )
void ALL::ALL<T,W>::setWork ( const W work )

If the given communicator is not a cartesian communicator the process grid parameters must also be set beforehand (!) using

void ALL::ALL<T,W>::setProcGridParams (
        const std::vector<int> &location,
        const std::vector<int> &size)

with the location of the current process and number of processes in each direction.

To trace the current domain better an integer tag can be provided, which is used in the domain output, with

void ALL::ALL<T,W>::setProcTag ( int tag )

and an observed minimal domain size in each direction can be set using

void ALL::ALL<T,W>::setMinDomainSize (
        const std::vector<T> &minSize )

Once these parameters are set call

void ALL::ALL<T,W>::setup()

so internal set up routines are run.

Balancing

To create the new domain vertices make sure the current vertices are set using setVertices and the work is set using setWork then call

void ALL::ALL<T,W>::balance()

and then the new vertices can be retrieved by using

std::vector<ALL::Point<T>> &ALL::ALL<T,W>::getVertices ()

or new neighbors with

std::vector<int> &ALL::ALL<T,W>::getNeighbors ()

Special considerations for the Fortran interface

The Fortran interface exists in two versions. Either in the form of

ALL_balance(all_object)

where the all object of type type(ALL_t) is given as first argument to each function and as more object oriented functions to the object itself. So the alternative call would be

all_object%balance()

The function names themselves are similar, i.e. instead of camel case they are all lowercase except the first ALL_ with underscores between words. So setProcGridParams becomes ALL_set_proc_grid_parms. For more usage info please check the Fortran example programs.

One important difference is the handling of MPI types, which change between the MPI Fortran 2008 interface as given by the mpi_f08 module and previous interfaces. In previous interfaces all MPI types are INTEGER s, but using the mpi_f08 module the communicator is of type(MPI_Comm). To allow using ALL_set_communicator directly with the communicator used in the user’s application, build the library with enabled Fortran 2008 features and this communicator type is expected.

Retrieving information from the balancer is also different, since most getter return (a reference to) an object itself. The Fortran subroutines set the values of its arguments. As an example

int work = all.getWork();

becomes

integer(c_int) :: work
call ALL_get_work(work) !or
!call all%get_work(work)

Since there is no exception handling in Fortran, the error handling from the libc is borrowed. So there are additional function that retrieve and reset an error number as well as an additional error message describing the error. These must be queried and handled by the user. An example of this usage is shown in the ALL_Staggered_f example when printing the VTK outlines.