pMatlab

Software Engineer: Nadya T. Bliss
Architect: Dr. Jeremy Kepner

Contact: [email protected]

Contributors:  Nadya T. Bliss, Jeremy Kepner, Bob Bond, Andy Funk, Ryan Haney, Hahn Kim, Julie Mullen, Albert Reuther, Edmund Wong.

REQUEST TO ALL USERS: Please read all of this 7-page manual (especially the section on ERROR HANDLING) before starting to use pMatlab.It is also helpful to read the 7-page MatlabMPI manual (see pMatlab/MatlabMPI/README).

PC users should read the 1-page manual for running MatlabMPI on a PC (see pMatlab/MatlabMPI/README.pc)

Additional documentation on how to write well-performing parallel
Matlab programs can be found in the book:

Parallel MATLAB for Multicore and Multinode Systems
by Jeremy Kepner, SIAM Press, 2009
https://my-siam-org.ezproxy.canberra.edu.au/Store/Product/viewproduct/?ProductId=1197

Installing and Running

1. Unpack pMatlab directory into a location that is visible to all computers.
2. Modify paths and add contents of pMatlab/startup.m to your ~/matlab/startup.m file. If you want to run using The MathWorks PCT you should uncomment the corresponding line to enable this functionality.
3. PC users should also add addpath .\MatMPI. Please see pMatlab/MatlabMPI/README.pc for more info.
4. OPTIONAL: You may need to read and edit pMatlab/MatlabMPI/src/MatMPI_Comm_settings.m to customize the behavior of MatlabMPI for your system.
5. Start Matlab from the command line (starting Matlab from the icon may result in inconsistent behavior).
6. Type "help pMatlab" to get a list of all the functions.
7. Type "help function_name" to get more information on a specific function.
8. Go to the "Examples/Mandelbrot" directory and type eval(pRUN('pMandelbrot',2,{})) to run the first example, which computes and displays the Mandebrot set.
9. Look at MatMPI/*.out to output from the different processors.
10. The same procedure can be followed to run any of the examples.
11. To run all of the examples, go to the "Examples/TestAll" directory and type "RUN" (edit the pTestAll.m file if you want to just run one a subset of the examples):

    AddOne/pAddOne.m
          Simple program that performs Y = X + 1.

    Mandelbrot/pMandelbrot.m
          Computes Mandelbrot set.

    ZoomImage/pZoomImage.m
          Zooms in on an image.

    IO/pIO.m
         Demonstrates parallel file IO.

    Blurimage/pBlurimage.m
         Convolves an image.

    Beamformer/pBeamformer.m
         Beamforms sensor data.

    Speedtest/pSpeedtest.m
         Tests message passing performance.

    Stream/pStream.m
         HPC Challenge Stream benchmark.

    RandomAccess/pRandomAccess.m
         HPC Challenge RandomAccess benchmark.

    FFT/pFFT.m
         HPC Challenge FFT benchmark.

    HPL/pHPL.m
         HPC Challenge High Performance Linpack (HPL) benchmark.

    TestAll/pTestAll.m
         Runs all of the above examples.

12. To run using a different number of processors, change the "Ncpus" variable in Examples/TestAll/RUN.m. All the examples should run with up to 8 processors.
13. To select which machines to run on, change the "machines" variable in Examples/TestAll/RUN.m. The machines variable canbe of the following forms:

    machines = {};
    Run on a local processor.

    machines = {'machine1' 'machine2'}) );
    Run on multiprocessors.

    machines = {'machine1:dir1' 'machine2:dir2'}) );
    Run on multiprocessors and communicate via dir1 and dir2,
    which must be visible to both machines.

Error Handling

pMatlab handles errors in the following manner.

1. pRUN automatically appends an "exit" statement to any scripts it runs. If an error is encountered, all the Matlab processes should die gracefully. All error logs should be recorded in files MatMPI/*.out.
2. If a Matlab job is waiting for a message that will never arrive, then you will have to kill it by hand by starting a new Matlab session and typing:

MPI_Abort

If this doesn't work, you will need to log into each machine, type"top" and kill the Matlab processes one by one. NOTE: pRUN automatically executes MPI_Abort before running the next job.

3. MatlabMPI can leave a variety of files lying around, which are best
   to delete once an error has occurred by starting Matlab and typing:

MatMPI_Delete_all

If this doesn't work, you can delete the files by hand. The files can be found in two places: the launching directory and the communication directory (which by default are the same place). NOTE: pRUN automatically executes MatMPI_Delete_all before running the next job.

In the launch directory, you may have leftover files that look like

            MatMPI/*

In the communication directory, you may have leftover files that look like:

           p<rank>_p<rank>_t<tag>_buffer.mat
           p<rank>_p<rank>_t<tag>_lock.mat

It is very important that you delete these files. In general, if you
are using a public directory to do communication (e.g.; /tmp), you should create a subdirectory first (e.g.; /tmp/joe) and use this directory for communication.

Files

Description of files/directories:

README	This file
startup.m	Edit and pass into your ~/matlab/startup.m
disclaimer	Disclaimer
examples/	Directory containing examples and benchmark programs
src/	pMatlab source files
MatlabMPI/	MatlabMPI library directory (see MatlabMPI/README)
PCTstubs	Functions for launching on top of MathWorks PCT

doc/

pMatlab_intro.pdf	Introduction to Parallel Programming and pMatlab
pMatlab_v2_param_sweep.pdf	Writing Parameter Sweep Applications with pMatlab
pMatlab_v2.0.1_func_ref.pdf	pMatlab Function Reference
pMatlabProgramming.pdf	Overview of distributed array concepts

src/

•    See contents.m for a description of all functions or type "help pMatlab"