Common Lisp C
Fetching latest commit…
Cannot retrieve the latest commit at this time.
README for CL-MPI Common Lisp Bindings for MPI Copyright (c) 2008,2009 Alex Fukunaga Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. =================================================== CONTENTS 0. INTRODUCTION 1. PLATFORMS 2. DEPENDENCIES 3. INSTALLATION 4. TESTING 5. NOTES 6. BUG REPORTS, PATCHES, ETC. =================================================== 0. Introduction CL-MPI is a portable, Common Lisp binding for the MPI message passing library. CL-MPI enables parallel programming in Common Lisp using a message-passing model on either a cluster of machines, or a single multicore machine. CL-MPI can also be used to provide "true" multiprocessing for some Common Lisp implementations which don't have native threading capabilities. =================================================== 1. PLATFORMS The long-term goal of CL-MPI is to provide a portable Common Lisp binding for MPI. I hope that eventually, any Common Lisp implementation which supports CFFI can be used with any MPI implementation. In the meantime, here are the currently tested configurations: Tested MPI implementations: - MPICH 22.214.171.124-2 (on Ubuntu Linux 8.04) - MPICH2-1.0.8p1 (on Ubuntu Linux 8.04) Tested Lisp implementations. - Steel Bank Common Lisp (SBCL) 1.0.22,1.0.24,1.0.28 - CMU Common Lisp 19e - Embeddable Common Lisp 10.7.1 Successfully tested configurations: 1) MPICH 126.96.36.199-2 on Ubuntu Linux 8.04 (64-bit)with SBCL 1.0.28 (64-bit) 2) MPICH 188.8.131.52-2 on Ubuntu Linux 8.04 with CMUCL 19e 3) MPICH2-1.0.8p1 on Ubuntu Linux 8.04 (64-bit) with SBCL 1.0.28 (64-bit) In principle, CL-MPI should work with any Common Lisp implementation supported by CFFI. The above are the only configurations I have tested so far. I have also tried OpenMPI 1.3.2 (Ubuntu Linux 8.04) + SBCL 1.0.28. While CL-MPI appears to build normally, any call to an MPI function results in a crash. This may or may not be be related to: https://bugs.launchpad.net/ubuntu/+source/openmpi/+bug/210273 https://bugs.launchpad.net/ubuntu/+source/python-numpy/+bug/307901 Since my own projects are currently based on MPICH 1.2 and MPICH2, I haven't put too much effort into OpenMPI. Please let me know if you get CL-MPI working with OpenMPI! =================================================== 2. DEPENDENCIES ASDF CFFI (C Foreign Function Interface), version 0.10.3 or later Tested with CFFI 0.10.4 =================================================== 3. INSTALLATION ------------------- QUICKSTART The included Makefile should work if you are using a standard installation of SBCL (where the sbcl binary is at /usr/local/bin), and MPICH1.2 installed with apt-get install on a Debian-based system: or a standard installatin of CMUCL and MPICH make asdf-links <-- creates links to this directory from the standard local make test-sbcl If your configurations differs from the above, or if the above make command doesn't result in the CL-MPI test suite being executed, then some installation steps may be necessary, so continue reading! ------------------ a) Install all of the systems which CL-MPI depends on: 1) Install a supported MPI implementation (currently only MPICH) 2) Install the CFFI library, version 0.10.3 or later. ------------------------------------------ b) Configure the installation. If your system is already fully configured for compilation of C programs, i.e. PATH to mpicc, MPI_LIB and MPI_INCLUDE are properly set, no additional configuration is necessary. The system also checks some predefined paths. (MPI_LIB and MPI_INCLUDE are not necessary if their correct values are ../lib and ../include relative to mpicc location) Otherwise, you need to edit cl-mpi-configure lisp, set values for *mpi-header-file*, *mpi-shared-library*, and ensure that the proper feature is pushed. If you are using mpich2, you may have to chdir into the mpich2-stub directory, and build a helper library called libmpiskeleton.so.1.0.1. This library is automatically used by the configure file if it exists. ------------------------------------------ c) Build CL-MPI Start Lisp in the directory where the CL-MPI sources reside, and build the CL-MPI system: CL-USER> (asdf:compile-system 'cl-mpi) Or (suggested if you are using SBCL or CMUCL), there is a Makefile which can be used in the cl-mpi direcory: make test-sbcl or make test-cmucl With Embeddable Common Lisp this library supports an alternative way of accessing the MPI libraries, namely direct linking to them via mpicc. In order to enable this, you have to push the :mpicc feature before the asd file is loaded, normally from your .eclrc file: (pushnew :mpicc *features*) You can also add it to the beginning of cl-mpi.asd. If your installation has only static versions of the MPI libraries, and cannot create MPI-enabled fasls, you can use the following commands to build an executable: (pushnew :mpicc-static *features*) (asdf:compile-system :cl-mpi) (asdf:make-mpicc-build <your system> :type :program) Note that in this mode the system can still be loaded normally with load-op, but any call to an mpi operation will result in an error. =================================================== 4. TESTING After installation is complete, we can try running the CL-MPI test program, which runs many tests to verify that the library works correctly. Do NOT use SLIME or the Lisp implementation's native REPL to start the test program. As with all MPI programs, you must start the MPI environment (e.g., using the standard "mpirun" command) and execute the Lisp program within MPI. The exact command to run will depend on your Lisp implementation and MPI implementation. EXAMPLE Commands for running the CL-MPI test suite: For SBCL and MPICH: Go to the directory where the CL-MPI sources are located, and at the shell prompt, enter: mpirun -np 2 /usr/local/bin/sbcl --load "run-mpi-test.lisp" The above command starts MPI (with the mpirun executable), using 2 processes. Each process starts SBCL (which, in this example, is located at /usr/local/bin/sbcl), and SBCL is instructed to load (and execute) the test suite (run-mpi-test.lisp). You may or may not have to enter the full path to SBCL, depending on your environment. Similarly, for CMUCL and MPICH, run the command: mpirun -np 2 /usr/local/bin/lisp -load "run-mpi-test.lisp" =================================================== 4. DOCUMENTATION/EXAMPLES: Sorry, not much user-level documentation yet, other than in doc strings and comments. Before using CL-MPI, it is necessary to be familiar with the MPI programming model. Here is an excellent MPI tutorial: https://computing.llnl.gov/tutorials/mpi/ In the cl-mpi/examples directory, there are several examples which illustrate basic usage, including: a hello world, numerical integration, Mandelbrot set image generator, and a version of the "GA-based image compression" made famous by Roger Alsing's "Evolving Mona Lisa" demo. =================================================== 5. NOTES: ** Unfortunately, CL-MPI can not be installed using ASDF-INSTALL because CL-MPI must be provided the location of the mpi.h header file, as well as the location of the MPI shared library, and I haven't figured out how to do this so that it works at least most of the time. Any patches to make installation easier are welcome! =================================================== 6. BUG REPORTS, PATCHES, etc. Please send bug reports, patches, comments, questions, to Alex Fukunaga at firstname.lastname@example.org