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