Documentation of dpgeamain2

Global Index (all files) (short | long) | Local contents | Local Index (files in subdir) (short | long)

Function Synopsis

[OP1, OP2, OP3] = dpgeamain(StrTask, P1, P2, varargin)

Help text

 DPGEA Matlab: Main function

 This function is the main function to use the DP-Toolbox functionality
 inside own projects.

 This function includes a number of subfunctions to achieve the 
 following tasks:
  - start the PVM system
  - start slaves (Matlab instances)
  - distribute tasks to slaves and collect the results
  - check running instances
  - kill slaves
  - clear left over data from buffers
  - get information about hosts (architecture, name and so on)

 By using this function a high level interface to the distribution of 
 tasks inside Matlab is given. The user must include just a few lines 
 of code in own projects.
 The high-level interface hides many of the complications of the 
 DP-Toolbox and PVM, offering just the functionality needed for solving 
 the problem.


 Syntax:  [OP1, OP2, OP3] = dpgeamain(StrTask, P1, P2, varargin)

 Input parameter:
    StrTask   - String defining the task to do
    P1 - Px   - Input parameters for the different tasks
                   see description of tasks for their meaning

 Output parameter:
    OP1 - OPy - Output parameters for the different tasks
                   see description of tasks for their meaning

 Task descriptions (string inside StrTask):
    'start'   - start PVM (if not already running) and spawn the slave 
                   proceses inside MATLAB instances,
                   instances can be spawned on specified machines (defined
                   by the parameter P1) or on default machines (determined
                   by PVM), the spawned slaves are added to the current
                   configuration
                P1: cell array with strings containing the names of the 
                    machines to start instances on or 
                    with a number, how many slaves to start
                no output parameters
           Example: start 3 slaves, one on bfo-galilei, two on bfo-kalman
            >> dpgeamain('start', {'bfo-galilei', 'bfo-kalman','bfo-kalman'})

    'master'  - distribute the received data to the Matlab instances (slaves),
                   do some robust test and do task balancing between clients,
                   receive the results from the slaves
                   distribution is done one task after another
                P1: string containing the function name to call with the data
                    (often called objective function)
                P2: matrix with data to distribute to function in P1, each 
                    row contains one data set
                varargin: (optional) cell array with additional parameters to 
                       send to function defined in P1, each cell element contains 
                       one parameter (each parameter could be a scalar, a vector or 
                       a matrix or a cell array ...)
                OP1: vector or matrix with results, each row corresponds to 
                     one row of the input data defined in P2
           Example: distribute 10 tasks to the function 'objfun1' (slaves must 
                       be started before) 
            >> data = rand(10, 100);  % 10 tasks, each with 100 variables
            >> Results = dpgeamain('master', 'objfun1', data);
                    distribute 1000 tasks to the function 'objdopi', 
                    send 2 additional parameters
            >> data = rand(1000, 20);  % 1000 tasks, each with 20 variables
            >> Tstart = 0; TEnd = 2;  % define additional parameters for 'objdopi'
            >> Results = dpgeamain('master', 'objdopi', data, {TStart, TEnd'});
              % 'objdopi'will be called from dpgeaslave with the following line
              % xxx stays for the number of the current task
              % >> Result_for_data_xxx = objdopi(data(xxx,:), TStart, TEnd);

    'check'   - checks, if pvmd and/or matlab is answering
                P1: == 'pvmd': checks just the pvmd of the given ID's
                    == 'matlab': checks the pvmd and calls the (not working)
                                 matlab instances
                P2: vector containing the number (PVM ID) of the instances
                    to check,
                OP1: vector containing the IDs of the instances, that are ok
                OP2: vector containing the IDs of the instances, that are not ok
           Example: check, if the pvm daemons of slaves are responding
            >> [IDs_ok, IDs_bad] = dpgeamain('check', 'pvmd', IDs_2_check);

    'clear'   - clear the recive buffer from arrays, used when suspending
                   some of the Matlab instances
                no input or output parameters

    'kill'    - kill/stop all or specified running MATLAB instances
                   and adjust global variables
                P1: vector containing the number (PVM ID) of the instances
                    to kill,
                    if omitted, all running instances are killed
                no output parameters
           Example: kill all running slaves
            >> dpgeamain('kill')

    'hostname'- look up information (hostname, architecture, speed) of
                   multiple instances
                P1: vector containing the number (PVM ID) of the instances
                    to get information for,
                    if omitted, the information for all started tasks is returned
                OP1: string array containing the hostname information
                OP2: string array containing the architecture information
                OP3: string array containing the speed information
           Example: get host name and architecture of ID1 and ID2
            >> [hn, ar] = dpgeamain('hostname', [ID1, ID2]);

 See also: dpgeaslave

Cross-Reference Information