Loading...
Searching...
No Matches
BALL::MPISupport Class Reference

`#include <BALL/SYSTEM/MPISupport.h>`

## Public Types

enum | TAGS { TAG_SYSTEM , TAG_OPTIONS }

## Public Member Functions

| MPISupport (MPI_Comm default_communicator=MPI_COMM_WORLD)
| MPISupport (int argc, char **argv, MPI_Comm default_communicator=MPI_COMM_WORLD, bool accept_communicator=true)
| ~MPISupport ()
Index | getRank ()
| Return the rank of this process.
Index | getSize ()
| Return the number of processes in MPI_COMM_WORLD.
MPI_Comm | getDefaultCommunicator ()
| Return the default communicator used for MPI calls.
void | setDefaultCommunicator (MPI_Comm default_communicator)
| Set the default communicator used for MPI calls.
bool | getFinalizeOnDestruct ()
void | setFinalizeOnDestruct (bool new_value)
| Decides whether MPI_Finalize will be called in the destructor.
void | setMpiInfo (const MPI_Info &mpi_info)
bool | isMaster ()
| Returns true if this process is the master, false otherwise.
void | init (int argc, char **argv, bool accept_communicator=true)
void | setBarrier ()
void | sendSystem (const System &system, bool broadcast=true, int receiver=0)
System * | receiveSystem (bool broadcast=true, int source=MPI_ANY_SOURCE)
void | sendOptions (const Options &options, bool broadcast=true, int receiver=0)
Options * | receiveOptions (bool broadcast=true, int source=MPI_ANY_SOURCE)
template<typename valuetype>
void | distributeDatapoints (const std::vector< valuetype > &input, std::vector< valuetype > &our_share)
template<typename valuetype>
void | acceptDatapoints (std::vector< valuetype > &our_share)
template<typename valuetype>
void | combineDatapoints (const std::vector< valuetype > &our_share)
template<typename valuetype>
void | acceptCombinedDatapoints (std::vector< valuetype > &combined_set, std::vector< valuetype > &our_share)
void * | distributeDatapoints (const void *input, int size, Size &numpoints, MPI_Datatype datatype)
void * | acceptDatapoints (Size &numpoints, MPI_Datatype datatype)
void | combineDatapoints (const void *input, int size, MPI_Datatype datatype)
void * | acceptCombinedDatapoints (const void *input, int size, Size &numpoints, MPI_Datatype datatype)
template<typename valuetype>
valuetype | getSum (valuetype &local_value)
template<typename valuetype>
valuetype | getProduct (valuetype &local_value)
template<typename valuetype>
valuetype | getMaximum (valuetype &local_value)
template<typename valuetype>
valuetype | getMinimum (valuetype &local_value)

## Protected Member Functions

void | registerTypes_ ()
void | sendPersistenceStream_ (const std::ostringstream &stream, int tag=MPI_ANY_TAG, bool broadcast=true, int receiver=0)
void | receivePersistenceStream_ (std::istringstream &in, int tag=MPI_ANY_TAG, bool broadcast=true, int source=0)

## Protected Attributes

Index | rank_
Index | comm_size_
bool | finalize_on_destruct_
MPI_Comm | default_communicator_
MPI_Info | mpi_info_object_
MPI_Datatype | mpi_Vector3_float_type_
MPI_Datatype | mpi_Vector3_double_type_

## Detailed Description

This class provides some of the most important MPI functions to BALL classes.

Definition at line 44 of file MPISupport.h.

## Member Enumeration Documentation

## TAGS

enum BALL::MPISupport::TAGS

TAGS used for send and receive operations

Enumerator
TAG_SYSTEM |
TAG_OPTIONS |

Definition at line 50 of file MPISupport.h.

## Constructor & Destructor Documentation

## MPISupport() [1/2]

BALL::MPISupport::MPISupport | ( | MPI_Comm | default_communicator = MPI_COMM_WORLD | ) |

Constructors and Destructors Default constructor. Does not call MPI_Init. default_communicator can be used to change the broadcasting behaviour of the MPI calls. The default is MPI_COMM_WORLD.

## MPISupport() [2/2]

BALL::MPISupport::MPISupport | ( | int | argc,
|  | char ** | argv,
|  | MPI_Comm | default_communicator = MPI_COMM_WORLD,
|  | bool | accept_communicator = true )

Detailed constructor. If MPI has not been initialized yet, argc and argv are passed to MPI_Init. If MPI has already been initialized, we can't re-initialize and throw a Precondition Exception. default_communicator can be used to change the broadcasting behaviour of the MPI calls. The default is MPI_COMM_WORLD.

If we find a parent of this process, we have been spawned somehow. In this case, we will by default use a communicator containing the old communicator of our parent and all spawned processes and none of the spawned processes will become a new master process. This behaviour can be avoided by setting accept_communicator to false

## ~MPISupport()

BALL::MPISupport::~MPISupport | ( |  | ) |

Destructor. By default, we call MPI_Finalize here. This can be avoided by setting the finalize_on_destruct_ flag of the class to false

## Member Function Documentation

## acceptCombinedDatapoints() [1/2]

void * BALL::MPISupport::acceptCombinedDatapoints | ( | const void * | input,
|  | int | size,
|  | Size & | numpoints,
|  | MPI_Datatype | datatype )

Combine distributed data from all processes in the communicator and return the result. The array input contains our own share of the data we need to combine. The number of points gathered is stored in numpoints. Note that all other processes in the communicator have to call combineDatapoints. The caller has to ensure that the returned array is free()'d. If memory allocation fails, 0 is returned.

## acceptCombinedDatapoints() [2/2]

template<typename valuetype>

void BALL::MPISupport::acceptCombinedDatapoints | ( | std::vector< valuetype > & | combined_set,
|  | std::vector< valuetype > & | our_share )

Accept datapoints that are combined from all processes of the communicator. If the required memory cannot be allocated, an Exception::OutOfMemory is thrown.

## acceptDatapoints() [1/2]

void * BALL::MPISupport::acceptDatapoints | ( | Size & | numpoints,
|  | MPI_Datatype | datatype )

Accept datapoints that are distributed by some source in the communicator. The caller has to ensure that the array is free()'d. If memory allocation fails, 0 is returned. The number of points we need to process is stored in numpoints.

## acceptDatapoints() [2/2]

template<typename valuetype>

void BALL::MPISupport::acceptDatapoints | ( | std::vector< valuetype > & | our_share | ) |

Accept datapoints that are distributed by some source in the communicator. Stores the result in our_share.

## combineDatapoints() [1/2]

template<typename valuetype>

void BALL::MPISupport::combineDatapoints | ( | const std::vector< valuetype > & | our_share | ) |

Combine datapoints from all processes of the communicator. Exactly one process has to accept the data by calling acceptCombinedDatapoints instead of combineDatapoints. If the required memory cannot be allocated, an Exception::OutOfMemory is thrown.

## combineDatapoints() [2/2]

void BALL::MPISupport::combineDatapoints | ( | const void * | input,
|  | int | size,
|  | MPI_Datatype | datatype )

Combine distributed data from all processes in the communicator. Note that all but one of the processes in the communicator have to call combineDatapoints, while exactly one has to call acceptCombinedDatapoints.

## distributeDatapoints() [1/2]

template<typename valuetype>

void BALL::MPISupport::distributeDatapoints | ( | const std::vector< valuetype > & | input,
|  | std::vector< valuetype > & | our_share )

Distribute input vector as evenly as possible over all processes in the communicator. Stores the part of the datapoints the sender itself has to process in our_share. Note that all processes in the communicator have to call acceptDatapoints.

## distributeDatapoints() [2/2]

void * BALL::MPISupport::distributeDatapoints | ( | const void * | input,
|  | int | size,
|  | Size & | numpoints,
|  | MPI_Datatype | datatype )

Distribute input of type datatype as evenly as possible over the processes in the communicator. Returns the datapoints the sender itself has to process. The number of points to process is stored in numpoints. Note that all processes in the communicator have to call acceptDatapoints. The caller has to ensure that the returned array is free()'d. If memory allocation fails, 0 is returned.

## getDefaultCommunicator()

MPI_Comm BALL::MPISupport::getDefaultCommunicator | ( |  | ) |

Return the default communicator used for MPI calls.

## getFinalizeOnDestruct()

bool BALL::MPISupport::getFinalizeOnDestruct | ( |  | ) |

Returns true if MPI_Finalize will be called in the destructor, false otherwise.

## getMaximum()

template<typename valuetype>

valuetype BALL::MPISupport::getMaximum | ( | valuetype & | local_value | ) |

Determine the maximum of the local_values of all processes. If this process is the master, this function will return the result. For all non-master processes, the result is undefined. This is implemented as a template function to encapsulate the MPI_Datatype - handling.

## getMinimum()

template<typename valuetype>

valuetype BALL::MPISupport::getMinimum | ( | valuetype & | local_value | ) |

Determine the minimum of the local_values of all processes. If this process is the master, this function will return the result. For all non-master processes, the result is undefined. This is implemented as a template function to encapsulate the MPI_Datatype - handling.

## getProduct()

template<typename valuetype>

valuetype BALL::MPISupport::getProduct | ( | valuetype & | local_value | ) |

Multiply the local_value of all processes. If this process is the master, this function will return the result. For all non-master processes, the result is undefined. This is implemented as a template function to encapsulate the MPI_Datatype - handling.

## getRank()

Index BALL::MPISupport::getRank | ( |  | ) |

Return the rank of this process.

Accessors.

## getSize()

Index BALL::MPISupport::getSize | ( |  | ) |

Return the number of processes in MPI_COMM_WORLD.

## getSum()

template<typename valuetype>

valuetype BALL::MPISupport::getSum | ( | valuetype & | local_value | ) |

Spawn new processes. This function allows the current instance to spawn new processes that can communicate via MPI. The spawned processes are assigned a new MPI_COMM_WORLD communicator by MPI, excluding /this/ process. We thus overwrite their default_communicator_, /and/ the default_communicator_ of /this/ process, with a communicator connecting all spawned processes with all processes in the default_communicator_ of this one. More complex communicator handling (like keeping the existing default_communicator_ of /this/ process) is currently not supported and can only be achieved by directly calling the corresponding MPI routines.

Note:

- this function relies on the MPI-2 standard. Thus, if only MPI-1 is supported, this function will not be compiled
- the executables that will be spawned do not need to be identical with the executable of the spawning process
- if the number of processes to spawn is set to zero, we will try to estimate the maximum sensible number using MPI_UNIVERSE
- currently, the use of MPI_Info objects to transmit information like search paths or hostnames to the spawned processes is not really supported. We merely pass an internal MPI_Info object that is set to MPI_INFO_NULL by default to MPI_Spawn. This object can be accessed from the outside using setMpiInfo(), but the external caller has to take care of the memory handling for this object

Parameters

  command | The path to the executable to spawn.
  argv | The command line arguments for the executable
  wanted_number_of_processes | The maximum number of processes to spawn

Returns
  The number of processes that were succesfully spawned Sum up the local_value of all processes. If this process is the master, this function will return the result. For all non-master processes, the result is undefined. This is implemented as a template function to encapsulate the MPI_Datatype - handling.

## init()

void BALL::MPISupport::init | ( | int | argc,
|  | char ** | argv,
|  | bool | accept_communicator = true )

Initialize MPI using argc and argv. If MPI_Init has already been called, a BALL_PRECONDITION_EXCEPTION is thrown. If we find a parent of this process, we have been spawned somehow. In this case, we will by default use a communicator containing the old communicator of our parent and all spawned processes and none of the spawned processes will become a new master process. This behaviour can be avoided by setting accept_communicator to false

## isMaster()

bool BALL::MPISupport::isMaster | ( |  | ) |

Returns true if this process is the master, false otherwise.

## receiveOptions()

Options * BALL::MPISupport::receiveOptions | ( | bool | broadcast = true,
|  | int | source = MPI_ANY_SOURCE )

Receive a BALL option class from the communicator. If broadcast is true, we expect a broadcast, otherwise a send. In case of directed send, the source can be given as well. Note that we will have to ensure that the Options are deleted ourselves.

## receivePersistenceStream_()

void BALL::MPISupport::receivePersistenceStream_ | ( | std::istringstream & | in,
|  | int | tag = MPI_ANY_TAG,
|  | bool | broadcast = true,
|  | int | source = 0 )

protected

Helper function for receiving BALL - objects: receives a string containing a persistence stream from the communicator and stores it in the istream

## receiveSystem()

System * BALL::MPISupport::receiveSystem | ( | bool | broadcast = true,
|  | int | source = MPI_ANY_SOURCE )

Receive a system from the communicator. If broadcast is true, we expect a broadcast, otherwise a send. In case of directed send, the source can be given as well. Note that we will have to ensure that the system is deleted ourselves.

## registerTypes_()

void BALL::MPISupport::registerTypes_ | ( |  | ) |

protected

Register MPI_Datatypes used for sending BALL objects around.

## sendOptions()

void BALL::MPISupport::sendOptions | ( | const Options & | options,
|  | bool | broadcast = true,
|  | int | receiver = 0 )

Send a BALL option class across the communicator. This function relies on BALL's XDRPersistenceManagement. If broadcast is true, all processes in default_communicator_ will receive the options. Note that all of these processes must call receiveOptions! If broadcast is set to false, the message is sent to receiver only.

## sendPersistenceStream_()

void BALL::MPISupport::sendPersistenceStream_ | ( | const std::ostringstream & | stream,
|  | int | tag = MPI_ANY_TAG,
|  | bool | broadcast = true,
|  | int | receiver = 0 )

protected

Helper function for sending BALL - objects: sends a string containing a persistence stream over the communicator.

## sendSystem()

void BALL::MPISupport::sendSystem | ( | const System & | system,
|  | bool | broadcast = true,
|  | int | receiver = 0 )

Send a system across the communicator. This function relies on BALL's XDRPersistenceManagement. If broadcast is true, all processes in default_communicator_ will receive the system. Note that all of these processes must call receiveSystem! If broadcast is set to false, the message is sent to receiver only.

## setBarrier()

void BALL::MPISupport::setBarrier | ( |  | ) |

Set an MPI_Barrier, i.e., this function will only return after all processes in the default_communicator_ have called this function (or have directly called MPI_Barrier). This can be used to syncronize the workflow.

## setDefaultCommunicator()

void BALL::MPISupport::setDefaultCommunicator | ( | MPI_Comm | default_communicator | ) |

Set the default communicator used for MPI calls.

## setFinalizeOnDestruct()

void BALL::MPISupport::setFinalizeOnDestruct | ( | bool | new_value | ) |

Decides whether MPI_Finalize will be called in the destructor.

## setMpiInfo()

void BALL::MPISupport::setMpiInfo | ( | const MPI_Info & | mpi_info | ) |

Set the internal MPI_Info object. This is currently only a workaround, and the memory handling (MPI_Info_free) has to be performed by the calling process.

## Member Data Documentation

## comm_size_

Index BALL::MPISupport::comm_size_

protected

Definition at line 330 of file MPISupport.h.

## default_communicator_

MPI_Comm BALL::MPISupport::default_communicator_

protected

Definition at line 332 of file MPISupport.h.

## finalize_on_destruct_

bool BALL::MPISupport::finalize_on_destruct_

protected

Definition at line 331 of file MPISupport.h.

## mpi_info_object_

MPI_Info BALL::MPISupport::mpi_info_object_

protected

Definition at line 333 of file MPISupport.h.

## mpi_Vector3_double_type_

MPI_Datatype BALL::MPISupport::mpi_Vector3_double_type_

protected

Definition at line 335 of file MPISupport.h.

## mpi_Vector3_float_type_

MPI_Datatype BALL::MPISupport::mpi_Vector3_float_type_

protected

Definition at line 334 of file MPISupport.h.

## rank_

Index BALL::MPISupport::rank_

protected

Definition at line 329 of file MPISupport.h.