2f7aeedaedae7761800b9571cb27cdb851dd6fed
[charm.git] / README
1                               Charm++ 5.4 (Release 1)
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 charm++ latest 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@thrift.cs.uiuc.edu:/expand6/cvsroot login
24
25       when CVS passwd is prompted, just type <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 PICKING A VERSION
36 =================
37
38 First, you need to decide which version of charm++ to use.  Your
39 choice is determined by three options:
40
41 1.)  The way a parallel program written in Charm++ will communicate:
42
43         "net-" Charm++ communicates using the regular TCP/IP stack
44 (UDP packets), which works everywhere but is fairly slow.  Use this
45 option for networks of workstations, clusters, or single-machine 
46 development and testing.
47
48         "mpi-" Charm++ communicates using MPI calls.  Use this for
49 machines with a good MPI implementation (such as the Origin 2000).
50
51         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
52 communicates using direct calls to the machine's communication primitives.
53
54         "sim-" and "uth-" are not actively maintained.  These are
55 single-processor versions: "uth-" simulates processors as user-level
56 threads; "sim-" switches between processors and counts communications.
57
58
59 2.)  Your operating system:
60
61         "linux"   Linux 
62         "win32"   MS Windows NT/98/2k (and MS Visual C++ compiler)
63         "cygwin"  MS Windows 98/NT/2k with Cygnus' Cygwin Unix layer
64         "irix"    SGI IRIX
65         "origin"  SGI Origin 2000 IRIX
66         "sol"     Solaris
67         "sun"     SunOS
68         "rs6k"    IBM R/S 6000 A/IX 
69         "sp"      IBM SP A/IX
70         "hp"      Hewlett-Packard HP-UX
71         "axp"     DEC Alpha DECUNIX
72         
73
74 3.)  Your compiler and other options.  Charm++ normally picks an
75 appropriate compiler for the system, but you may select another
76 compiler:
77
78         "-cc"      The OEM C/C++ compiler.  When given, this
79 will override the choice of the GNU C/C++ compiler.
80         "-kcc"     Kuck & Associates C++ compiler.
81         "-acc"     Uses HP's aCC instead of CC.
82
83 Some operating systems have other options, such as:
84         "-x86"     For Solaris, use PC hardware (instead of Sun).
85         "-axp"     For Linux, use Alpha hardware (instead of PC).
86         "-64"      For IRIX, use -64 instead of -32. 
87
88 You may also choose to enable direct SMP support with a "-smp"
89 version, which may result in more efficient communication in
90 a cluster-of-SMPs.  A "-smp" version will communicate using
91 shared memory within a machine; but message passing across machines.
92 "-smp" is currently only available with "net-" versions.
93 Because of locking, "-smp" may slightly impact non-SMP performance.
94
95
96 Your Charm++ version is made by concatenating all three options, e.g.:
97
98 "net-linux"     Charm++ for a network of Linux workstations, compiled
99                 using g++.
100 "net-linux-kcc" Charm++ for a network of Linux workstations, compiled
101                 using Kuck & Associates C++ compiler.
102 "net-linux-smp" Charm++ for a network of Linux SMP workstations,
103                 compiled using g++.
104 "net-sol-cc"    Charm++ for a network of Sun workstations, 
105                 compiled using Sun CC.
106 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
107
108
109
110 BUILDING THE SOURCE
111 ===================
112
113 If you have downloaded a binary version of Charm++, you can skip
114 this step-- Charm++ should already be compiled.  For win32 systems,
115 see README.win32; for Cygwin version, see README.cygwin; for net- version, 
116 see README.net.
117
118 Once you have decided on a version, unpack Charm++, cd into charm,
119 and run
120
121      > ./build _target_ _version_ _opts_
122
123 Where _target_ is one of
124         "charm++"  The basic Charm++ language.
125         "AMPI"     An implementation of MPI on top of Charm++
126         "FEM"      A Finite-Element framework on top of Charm++
127
128 And _opts_ are command line options passed to the charmc compile script.
129 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
130 accepted.
131
132 For example, on a Linux machine, you would run
133      > ./build charm++ net-linux -O
134
135
136 This will construct a _version_ directory, link over all
137 the Charm++ source code into _version_/tmp, build the entire
138 Charm++ runtime system in _version_/tmp, and link sample programs 
139 into _version_/pgms.
140
141 Several #define's control the compilation of Charm++.  Some of these
142 #define's can be found in src/_version_/conv-mach.h.  #define's can
143 also be specified on the command line, using the -D option.  For
144 example,
145     > ./build charm++ net-linux -O -DCMK_OPTIMIZE=1
146
147 CMK_OPTIMIZE: Turn on optimizations in Charm++.
148
149
150 BUILDING A PROGRAM
151 ==================
152
153 To make a sample program, cd into _version_/pgms/charm++/queens/.
154 This program solves the N-queens problem-- find how many ways there 
155 are to arrange N queens on an NxN chess board such that none may 
156 attack another.  
157
158 To build the program, type make.  You should get an
159 executable named "pgm".
160
161
162 RUNNING A PROGRAM
163 ==================
164
165 Following the previous example, to run the program on two processors, type
166
167      > ./charmrun ./pgm 12 100 +p2
168
169 This should run for a few seconds, and print out:
170 There are 14200 Solutions to 12 queens. Finish time=4.030000
171
172 Charmrun is now available on all platforms. Depending on what platform you are 
173 running charm program, charmrun could be just a shell script which is a wrapper
174  for mpirun, for example, in mpi- version. The idea of charmrun is trying to 
175 provide a uniform parameters across all platforms.
176
177 For net- version, charmrun is an executable which invokes rsh or ssh to start 
178 node programs on remote machines. Remember that you should set up a ~/.nodelist that enumerates all the machines you want to run jobs on, otherwise it will
179 create a default ~/.nodelist for you that contains only localhost. Here is a 
180 typical .nodelist file:
181
182 group main ++shell /bin/ssh
183 host machinename
184
185 The default remote shell program is rsh, but you can define differnt remote 
186 shell you like to start remote processes in the ++shell option. You should 
187 also make sure that you can rsh or ssh to these machines without passwd 
188 authentication. Just type following command to verify:
189      > rsh(ssh) machinename date
190 If this gives you current date immediately, your running environment with this 
191 node has been setup correctly.
192
193 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
194 "++local" options. No remote shell invocation is needed in this case. It starts
195  node programs right on your local machine. This could be useful if you just 
196 want to run program on only one machine, for example, your laptop. This
197 can save you all the hassle of setting up rsh/ssh or charmd daemons.
198 To use this option, just type:
199      
200      > ./charmrun ++local ./pgm 12 100 +p2
201
202 However, for best performance, you should launch one node program per processor.
203
204 For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" under doc/install.
205
206 FOR MORE INFORMATION
207 ====================
208
209 The Charm++ web page, with documentation, more programs,
210 and the latest version of Charm++, is at
211         http://charm.cs.uiuc.edu/
212
213 The Charm++ mailing list, for questions, comments, suggestions, 
214 improvements, or bug reports is
215         ppl@cs.uiuc.edu
216
217
218 AUTHORS
219 =======
220
221 Charm++ is written and maintained by the Parallel Programming Lab, in
222 the Computer Science department at the University of Illinois at
223 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
224 have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
225 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
226 Gupta, Attila Gursoy, Balkrishna Ramkumar, Amitabh B. Sinha, Nimish
227 Shah, Sanjeev Krishnan, Jayant DeSouza, Parthasarathy Ramachandran,
228 Jeff Wright, Michael Lang, Jackie Wang, Fang Hu, Michael Denardo,
229 Joshua Yelon, Narain Jagathesan, Zehra Sura, Krishnan Varadarajan, and
230 Sameer Paranjpye.  Current developers include Milind Bhandarkar,
231 Robert Brunner, Terry Wilmarth, Gengbin Zheng, Jayant Desouza, Orion
232 Lawlor, Karthik Mahesh, and Neelam Saboo.
233