# Module Scientific.BSP

This module contains high-level parallelization constructs based on the Bulk Synchronous Parallel (BSP) model.

Parallelization requires a low-level communications library, which can be either BSPlib or MPI. Programs must be run with the bsppython or mpipython executables in order to use several processors. When run with a standard Python interpreter, only one processor is available.

A warning about object identity: when a communication operation transmits a Python object to the same processor, the object in the return list can either be the sent object or a copy of it. Application programs thus should not make any assumptions about received objects being different from sent objects.

# Submodules:

- Module Scientific.BSP.Console

- Module Scientific.BSP.IO

## Class ParValue: Global data

ParValue instances are created internally, but are not meant to be created directly by application programs. Use the subclasses instead.

ParValue objects (and those of subclasses) implement the standard arithmetic and comparison operations. They also support attribute requests which are passed on to the local values; the return values are ParValue objects. ParValue objects can also be called if their local values are callable.

Methods:

- put(pid_list)

  Sends the local data to all processors in pid_list (a global object). Returns a ParValue object whose local value is a list of all the data received from other processors. The order of the data in that list is not defined.

- get(pid_list)

  Requests the local data from all processors in pid_list (a global object). Returns a ParValue object whose local value is a list of all the data received from other processors. The order of the data in that list is not defined.

- broadcast(from_pid=`0`)

  Transmits the local data on processor from_pid to all processors. Returns a ParValue object.

- fullExchange()

  Transmits the local data of each processor to all other processors. Returns a ParValue object.

- reduce(operator, zero)

  Performs a reduction with operator over the local values of all processors using zero as initial value. The result is a ParValue object with the reduction result on processor 0 and zero on all other processors.

- accumulate(operator, zero)

  Performs an accumulation with operator over the local values of all processors using zero as initial value. The result is a ParValue object whose local value on each processor is the reduction of the values from all processors with lower or equal number.

- alltrue()

  Returns 1 (local value) if the local values on all processors are true.

- anytrue()

  Returns 1 (local value) if at least one of the local values on all processors is true.

## Class ParConstant: Global constant

A subclass of ParValue.

Constructor: ParConstant(value)

value

  any local or global object

## Class ParData: Global data

A subclass of ParValue

Constructor: ParData(function)

function

  a function of two arguments (processor number and number of processors in the machine) whose return value becomes the local value of the global object.

## Class ParSequence: Global distributed sequence

A subclass of ParValue.

Constructor: ParSequence(full_sequence)

full_sequence

  any indexable and sliceable Python sequence

The local value of a ParSequence object is a slice of full_sequence, which is constructed such that the concatenation of the local values of all processors equals full_sequence.

## Class ParMessages: Global message list

A subclass of ParValue.

Constructor: ParMessage(messages)

messages

  a global object whose local value is a list of (pid, data) pairs.

Methods:

- processorIds()

  Returns a ParValue object whose local value is a list of all processor Ids referenced in a message.

- data()

  Returns a ParValue object whose local value is a list of all data items in the messages.

- exchange()

  Sends all the messages and returns a ParValue object containing the received messages.

## Class ParTuple: Global data tuple

A subclass of ParValue.

Constructor: ParTuple(x1, x2, ...)

x1, x2, ...

  global objects

ParTuple objects are used to speed up communication when many data items need to be sent to the same processors. The construct a, b, c = ParTuple(a, b, c).put(pids) is logically equivalent to a = a.put(pids); b = b.put(pids); c = c.put(pids) but more efficient.

## Class ParAccumulator: Global accumulator

A subclass of ParValue.

Constructor: ParAccumulator(operator, zero)

operator

  a local function taking two arguments and returning one argument of the same type.

zero

  an initial value for reduction.

ParAccumulator objects are used to perform iterative reduction operations in loops. The initial local value is zero, which is modified by subsequent calls to the method addValue.

Methods:

- addValue(value)

  Replaces the internal value of the accumulator by internal_value = operator(internal_value, value).

- calculateTotal()

  Performs a reduction operation over the current local values on all processors. Returns a ParValue object.

## Class ParFunction: Global function

A subclass of ParValue.

Constructor: ParFunction(local_function)

local_function

  a local function

Global functions are called with global object arguments. The local values of these arguments are then passed to the local function, and the result is returned in a ParValue object.

## Class ParRootFunction: Asymmetric global function

Constructor: ParRootFunction(root_function, other_function=None)

root_function

  the local function for processor 0

other_function

  the local function for all other processors. The default is a function that returns None.

Global functions are called with global object arguments. The local values of these arguments are then passed to the local function, and the result is returned in a ParValue object.

A ParRootFunction differs from a ParFunction in that it uses a different local function for processor 0 than for the other processors. ParRootFunction objects are commonly used for I/O operations.

## Class ParIterator: Parallel iterator

Constructor: ParIterator(global_sequence)

global_sequence

  a global object representing a distributed sequence

A ParIterator is used to loop element by element over a distributed sequence. At each iteration, the returned item (a global object) contains different elements of the distributed sequence.

## Class ParIndexIterator: Parallel index iterator

Constructor: ParIndexIterator(global_sequence)

global_sequence

  a global object representing a distributed sequence

A ParIndexIterator is used to loop index by index over one or more distributed sequences. At each iteration, the returned item (a global index object) contains indices of different elements of the distributed sequence(s). The index objects can be used to index any ParValue object whose local value is a sequence object.

## Class ParClass: Global class

Constructor: ParClass(local_class)

local_class

  a local class

Global classes are needed to construct global objects that have more functionalities than offered by the ParValue class hierarchy. When an instance of a global class is generated, each processor generates an instance of local_class that becomes the local value of the new global object. Attribute requests and method calls are passed through to the local objects and the results are assembled into global objects (ParValue or ParFunction). The arguments to methods of a global class must be global objects, the local class methods are then called with the corresponding local values.

The local objects are initialized via the special method __parinit__ instead of the usual __init__. This method is called with two special arguments (processor number and total number of processors) followed by the local values of the arguments to the global object initialization call.

The local classes must inherit from the base class ParBase (see below), which also provides communication routines.

## Class ParBase: Distributed data base class

Local classes that are to be used in global classes must inherit from this class.

Methods:

- put(data, pid_list)

  Send data to all processors in pid_list. Returns the list of received objects.

- get(data, pid_list)

  Requests the local values of data of all processors in pid_list. Returns the list of received objects.

- broadcast(data, from_pid=`0`)

  Sends the local value of data on processor from_pid to all processors. Returns the list of received objects.

- exchangeMessages(message_list)

  Sends the (pid, data) messages in message_list to the destination processors. Returns the list of incoming data.