pMatlab

pMatlab Documentation

Parallel MATLAB for Multicore and Multinode Systems
by Jeremy Kepner, SIAM Press, 2009
[Please cite this book in all publications that use pMatlab.]

  • Introduction to Parallel Programming and pMatlab (pdf)
  • Writing Parameter Sweep Applications with pMatlab (pdf)
  • pMatlab Function Reference (pdf)
  • pMatlab Programming (ppt)

    pMatlab v2.0.15

    Engineer: Prof. Nadya T. Bliss
    Architect: Dr. Jeremy Kepner
    Contact: pmatlab@ll.mit.edu

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

    DOWNLOAD

    pMatlab-v2.0.15.tgz


    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)

    INTRODUCTION

    MATLAB and GNU Octave are popular programming languages for implementing numerical computations and are widely used for algorithm development, simulation, data reduction, testing, and system evaluation. Many of these computations could benefit from faster execution on a parallel computer. There have been many previous attempts to provide an efficient mechanism for running Matlab programs on parallel computers. pMatlab provides a set of data structures and functions that implement distributed arrays. Parallel array programming has proven to be an effective programming style for a wide variety of parallel applications and is consistent with standard Matlab programming style. The primary advantages of distributed array programming are:

    REQUIREMENTS
    pMatlab uses MatlabMPI (included with pMatlab download) for launching programs and communicating between processors and thus has the following requirements

    Because MatlabMPI uses file i/o for communication, there must be a directory that is visible to every machine (this is usually also required in order to install Matlab). This directory defaults to the directory that the program is launched from, but can be changed when you launch your pMatlab program.

    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 can be 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.

    1. 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/username) 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.ppt Overview of distributed array concepts

    src/


    Copyright 2005-2008, Massachusetts Institute of Technology.  All rights reserved.

    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    MATLAB is a registered MathWorks trademark. Reference to commercial products, tradenames, trademarks, or manufacturer does not constitute or imply endorsement.