3f9ec1322b97d934592a6de2096905d3eae568c1
[charm.git] / README
1                               Charm++ 5.6
2
3        Copyright (C) 1989-2000 Regents of the University of Illinois
4
5 INTRODUCTION
6 ============
7
8 Charm++ is a message-passing parallel language and runtime system.
9 It is implemented as a set of libraries for C++, is efficient,
10 and is portable to a wide variety of parallel machines.
11 Source code is provided, and non-commercial use is free.
12
13
14 GETTING THE LATEST CHARM SOURCE
15 ===============================
16
17 You can use our anonymous cvs server to checkout the latest charm++ source code.
18 (It may not be the latest stable version though) 
19 What you need to do is as following:
20
21 1. login the cvs server:
22
23       cvs -d :pserver:checkout@charm.cs.uiuc.edu:/cvsroot login
24
25       when CVS password is prompted, just press enter.
26 2. checkout charm:
27
28       cvs co -P charm
29
30       You should get latest charm source tree.
31 3. logout the cvs server:
32
33       cvs logout
34
35
36 PICKING A VERSION
37 =================
38
39 First, you need to decide which version of charm++ to use. The "build" 
40 script in charm source directory takes several command line options to
41 compile Charm++. The command line syntax is:
42
43 build <target> <version> [options ...] [--basedir=dir] [--libdir=dir] [--incdir=dir] [charmc-options ...]
44
45 REQUIRED:
46 ---------
47 <target> specifies the parts of Charm++ to compile.  The most often used 
48   <target> is charm++, which will compile the key Charm++ executables and 
49   runtime libraries.
50 <versions> defines the CPU, OS and Communication layer of the machines.  See 
51   "How to choose a <version>" below for details.
52
53 OPTIONAL:
54 ---------
55 <options> defines more detailed information of the compilations, including 
56   compilers, features to support, etc.  See "How to choose <option>"
57   below.
58 [--libdir=dir] specify additional lib paths for building Charm++.
59 [--incdir=dir] specify additional include paths for building Charm++.
60 [--basedir=dir] a shortcut to specify additional include and lib paths for 
61                building Charm++, the include path is dir/include and lib path 
62                is dir/lib.
63
64
65 Running build script, a directory of the name of combination of version and 
66 options like "<version>-<option1>-<option2>-..." will be created and build 
67 script will compiler Charm++ under this directory.
68 For example:
69
70 ./build charm++ net-linux scyld icc tcp
71
72 will build charm++ in a directory: net-linux-scyld-tcp-icc/.
73 for Linux version on Scyld using TCP for communication, compiled with 
74 Intel C++ compiler.
75
76 You can specify multiple options, however you should only give one compiler 
77 option. The sequence of the options are not important given in build script, 
78 only one directory name will be generated, following the rules:
79 1. compiler option will be at the end;
80 2. other options are shorted alphabetically.
81
82 **** How to choose a <version> ****
83
84 Here is the table for choosing correct version. The default setting of compiler
85 in Charm version is gcc/g++. However, one can use <options> to specify other 
86 compilers. See the detailed explanation of the <options> below.
87 (Note: this isn't a complete list.  Run ./build for a complete listing)
88
89 Charm version          OS        Communication     Compiler  
90 -------------       ---------    --------------   --------------------
91 net-linux            PC Linux       UDP/Myrinet   GNU compiler
92 net-linux-ia64       IA64 Linux     UDP/Myrinet   GNU compiler
93 net-axp              Alpha          UDP           GNU compiler
94 net-cygwin           Win32/cygwin   UDP           GNU compiler
95 net-win32            Win32          UDP           MS Visual C++
96 net-sol              Solaris        UDP           GNU compiler
97 net-irix             IRIX           UDP           GNU compiler
98 net-hp               HP-UX          UDP           GNU compiler
99 net-ppc-darwin       MacOS X        UDP           GNU C++ compiler
100 mpi-linux            PC Linux       MPI           GNU compiler
101 mpi-linux-ia64       IA64 Linux     MPI           GNU compiler
102 mpi-axp              Alpha          MPI           GNU compiler
103 mpi-linux-axp        Alpha Linux    MPI           GNU compiler
104 mpi-origin           Origin2000     MPI           C++ compiler
105 mpi-sp               AIX            MPI           AIX xlC Compiler 
106 origin2000           Origin2000  shared-mem       SGI C++ compiler     
107 t3e                  Cray T3E    shared-mem       Cray C++ compiler
108
109
110 To choose <version>, your choice is determined by three options:
111
112 1.)  The way a parallel program written in Charm++ will communicate:
113
114         "net-" Charm++ communicates using the regular TCP/IP stack
115 (UDP packets), which works everywhere but is fairly slow.  Use this
116 option for networks of workstations, clusters, or single-machine 
117 development and testing.
118
119         "mpi-" Charm++ communicates using MPI calls.  Use this for
120 machines with a good MPI implementation (such as the Origin 2000).
121
122         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
123 communicates using direct calls to the machine's communication primitives.
124
125         "sim-" and "uth-" are not actively maintained.  These are
126 single-processor versions: "uth-" simulates processors as user-level
127 threads; "sim-" switches between processors and counts communications.
128
129
130 2.)  Your operating system:
131
132         "linux"   Linux 
133         "win32"   MS Windows with MS Visual C++ compiler
134         "cygwin"  MS Windows with Cygnus' Cygwin Unix layer
135         "irix"    SGI IRIX
136         "origin"  SGI Origin 2000 IRIX
137         "sol"     Solaris
138         "sun"     SunOS
139         "rs6k"    IBM R/S 6000 A/IX 
140         "sp"      IBM SP A/IX
141         "hp"      Hewlett-Packard HP-UX
142         "axp"     DEC Alpha DECUNIX
143         
144
145 3.)  Some operating systems have other options, such as:
146         "-x86"     For Solaris, use PC hardware (instead of Sun).
147         "-axp"     For Linux, use Alpha hardware (instead of PC).
148
149 Your Charm++ version is made by concatenating the options, e.g.:
150
151 "net-linux"     Charm++ for a network of Linux workstations, compiled
152                 using g++.
153 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
154
155
156 **** How to choose <options> ****
157
158 <version> above defines the most important OS, CPU and Communication of 
159 your machine, and most of time, it use the GNU gcc as default compiler. 
160 To use different compiler or demand additional special feature support, you 
161 need to choose <options> from the following list:
162
163 * gcc3  - GNU GCC/G++ version 3
164 * acc  - HP aC++ compiler
165 * cc  - For Sun WorkShop C++ compilers;
166 * cc64 - For 64 bits Sun WorkShop C++ compilers;
167 * cxx - DIGITAL C++ compiler;
168 * kcc - KAI C++ compiler;
169 * pgcc - Portland Group's C++ compiler;
170 * icc - Intel C/C++ compiler for Linux IA32
171 * ecc - Intel C/C++ compiler for Linux IA64
172 * mpcc - SUN Solaris C++ compiler for MPI.
173
174 * scyld - support Beowulf Scyld;
175 * gm - support MyriCom's Myrinet GM library;
176 * vmi - support NCSA's VMI library;
177
178 * tcp - for net- version, default communication is via UDP. Using option
179         tcp will switch to TCP. TCP version of CHarm++ is usually slower
180         than UDP, but it is more reliable.
181 * smp - Enable direct SMP support.  An "smp" version communicates using
182         shared memory within a machine; but normal message passing across 
183         machines. Because of locking, "smp" may slightly impact non-SMP 
184         performance. Try your application to decide if enabling smp mode 
185         improves performance.
186
187 * bluegene - compile Charm++ as running on Blue Gene emulator.
188 * help - show supported options for a version. For example, for net-linux, 
189          running:
190          > ./build charm++ net-linux help
191          will give:
192          supported options: gcc3 gm icc kcc pgcc scyld smp bluegene tcp
193
194
195 BUILDING THE SOURCE
196 ===================
197
198 If you have downloaded a binary version of Charm++, you can skip
199 this step-- Charm++ should already be compiled.  For win32 systems,
200 see README.win32; for Cygwin version, see README.cygwin; for net- version, 
201 see README.net.
202
203 Once you have decided on a version, unpack Charm++, cd into charm,
204 and run
205
206      > ./build <target> <version> <opts>
207
208 <target> is one of
209         "charm++"  The basic Charm++ language.
210         "AMPI"     An implementation of MPI on top of Charm++
211         "FEM"      A Finite-Element framework on top of Charm++
212
213 <version> is described above
214
215 <opts> are build-time options (such as the compiler or "smp"), 
216 or command line options passed to the charmc compile script.
217 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
218 accepted.
219
220 For example, on a Linux machine, you would run
221      > ./build charm++ net-linux -O
222
223 This will construct a net-linux directory, link over all
224 the Charm++ source code into net-linux/tmp, build the entire
225 Charm++ runtime system in net-linux/tmp, and link sample programs 
226 into net-linux/pgms.
227
228 Several #define's control the compilation of Charm++.  Some of these
229 #define's can be found in src/<version>/conv-mach.h.  #define's can
230 also be specified on the command line, using the -D option.  For
231 example,
232     > ./build charm++ net-linux -O -DCMK_OPTIMIZE=1
233
234 CMK_OPTIMIZE: Turn on optimizations in Charm++/Converse. This disables most of
235 the run-time checking performed by Converse and Charm++ runtime. This option
236 should be used only after the program has been debugged. Also, this option
237 disables Converse/Charm++ tracing mechanisms such as projections and summary.
238
239
240 BUILDING A PROGRAM
241 ==================
242
243 To make a sample program, cd into pgms/charm++/queens/.
244 This program solves the N-queens problem-- find how many ways there 
245 are to arrange N queens on an NxN chess board such that none may 
246 attack another.
247
248 To build the program, type make.  You should get an
249 executable named "pgm".
250
251
252 RUNNING A PROGRAM
253 ==================
254
255 Following the previous example, to run the program on two processors, type
256
257      > ./charmrun ./pgm 12 100 +p2
258
259 This should run for a few seconds, and print out:
260 There are 14200 Solutions to 12 queens. Finish time=4.030000
261
262 Charmrun is used to provide a uniform interface to run charm programs.
263 On some platforms, charmrun is just a shell script which calls the 
264 platform-specific start program, such as mpirun on mpi versions.
265
266 For net- version, charmrun is an executable which invokes rsh or ssh to start 
267 node programs on remote machines. You should set up a ~/.nodelist that 
268 enumerates all the machines you want to run jobs on, otherwise it will
269 create a default ~/.nodelist for you that contains only localhost. Here is a 
270 typical .nodelist file:
271
272 group main ++shell /bin/ssh
273 host <machinename>
274
275 The default remote shell program is rsh, but you can define different remote 
276 shell you like to start remote processes in the ++shell option. You should 
277 also make sure that you can rsh or ssh to these machines without password 
278 authentication. Just type following command to verify:
279      > rsh <machinename> date
280 If this gives you current date immediately, your running environment with this 
281 node has been setup correctly.
282
283 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
284 "++local" options. No remote shell invocation is needed in this case. It starts
285 node programs right on your local machine. This could be useful if you just 
286 want to run program on only one machine, for example, your laptop. This
287 can save you all the hassle of setting up rsh/ssh or charmd daemons.
288 To use this option, just type:
289      
290      > ./charmrun ++local ./pgm 12 100 +p2
291
292 However, for best performance, you should launch one node program per processor.
293
294 For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" 
295 under doc/install.
296
297
298 FOR MORE INFORMATION
299 ====================
300
301 The Charm++ web page, with documentation, more programs,
302 and the latest version of Charm++, is at
303         http://charm.cs.uiuc.edu/
304
305 The Charm++ mailing list, for questions, comments, suggestions, 
306 improvements, or bug reports is
307         ppl@cs.uiuc.edu
308
309
310 AUTHORS
311 =======
312
313 Charm++ was created and is maintained by the Parallel Programming Lab, 
314 in the Computer Science department at the University of Illinois at
315 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
316 have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
317 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
318 Gupta, Attila Gursoy, Balkrishna Ramkumar, Amitabh B. Sinha, Nimish
319 Shah, Sanjeev Krishnan, Jayant DeSouza, Parthasarathy Ramachandran,
320 Jeff Wright, Michael Lang, Jackie Wang, Fang Hu, Michael Denardo,
321 Joshua Yelon, Narain Jagathesan, Zehra Sura, Krishnan Varadarajan, and
322 Sameer Paranjpye.  Current developers include Milind Bhandarkar,
323 Robert Brunner, Terry Wilmarth, Gengbin Zheng, Jayant Desouza, Orion
324 Lawlor, Karthik Mahesh, and Neelam Saboo.
325
326
327
328