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.