ZC API: Rename registration mode variable from mode to regMode
[charm.git] / README
1                            Charm++
2
3        Copyright (C) 1989-2019 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 SOURCE
15 =========================
16
17 You can use anonymous Git access to obtain the latest Charm++ source
18 code, as follows:
19
20      > git clone http://charm.cs.illinois.edu/gerrit/charm
21
22
23 BUILD CONFIGURATION
24 ===================
25
26 QUICK START:
27 ------------
28 First-time users are encouraged to run the top-level "build" script and follow its lead:
29      > ./build
30
31
32 ADVANCED BUILD OPTIONS:
33 -----------------------
34
35 First, you need to decide which version of charm++ to use. The "build"
36 script takes several command line options to compile Charm++. The command line syntax is:
37
38      > build <target> <version> [options ...]
39                                 [--basedir=dir] [--libdir=dir] [--incdir=dir]
40                                 [charmc-options ...]
41
42 For detailed help messages, pass -h or --help to the build script, i.e.
43      > ./build --help
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.  Other common targets are "AMPI" and "LIBS".
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
67 the build script will compile Charm++ under this directory.
68
69 For example, on an ordinary Linux PC:
70
71      > ./build charm++ netlrts-linux-x86_64
72
73 will build charm++ in the directory: netlrts-linux-x86_64/. The communication
74 defaults to UDP packets and the compiler to gcc.
75
76 For a more complex example, consider a shared-memory build with the
77 Intel C++ compiler, where you want the communication to happen over TCP sockets:
78
79      > ./build charm++ netlrts-linux-x86_64 smp icc tcp
80
81 will build charm++ in the directory: netlrts-linux-x86_64-smp-tcp-icc/.
82
83 You can specify multiple options, however you can use at most one compiler
84 option. The sequencing of options given to the build script should follow the rules:
85 1. compiler option will be at the end;
86 2. other options are sorted alphabetically.
87
88 **** How to choose a <version> ****
89
90 Here is the table for choosing a correct build version. The default setting of compiler
91 in Charm++ is gcc/g++ on Linux and Clang on MacOS. However, one can use <options> to specify other
92 compilers. See the detailed explanation of the <options> below.
93 (Note: this isn't a complete list.  Run ./build for a complete listing)
94
95 Charm version                OS         Communication    Default Compiler
96 -------------             ---------     --------------   --------------------
97 netlrts-linux-x86_64       Linux            UDP            GNU compiler
98 netlrts-darwin-x86_64      MacOS X          UDP            Clang C++ compiler
99 netlrts-win-x86_64         Windows          UDP            MS Visual C++
100 mpi-linux-x86_64           Linux            MPI            GNU compiler
101 multicore-darwin-x86_64    MacOS X          Shared memory  Clang C++ compiler
102 pamilrts-bluegeneq         CNK              PAMI           BGClang C++ compiler
103 gni-crayxc                 Linux            GNI            CC (whatever PrgEnv module is loaded)
104 gni-crayxe                 Linux            GNI            CC (whatever PrgEnv module is loaded)
105 verbs-linux-x86_64         Linux            IB Verbs       GNU compiler
106 ofi-linux-x86_64           Linux            OFI            GNU compiler
107
108
109 To choose <version>, your choice is determined by two options:
110
111 1.)  The way a parallel program written in Charm++ will communicate:
112
113         "netlrts-" Charm++ communicates using the regular TCP/IP stack
114 (UDP packets), which works everywhere but is fairly slow.  Use this
115 option for networks of workstations, clusters, or single-machine
116 development and testing.
117
118         "gni-", "pamilrts-", "verbs-", "ofi-" Charm++
119 communicates using direct calls to the machine's communication primitives.
120 Use these versions on machines that support them for best performance.
121
122         "mpi-" Charm++ communicates using MPI calls.
123
124         "multicore-" Charm++ communicates using shared memory within a single node.
125
126
127 2.)  Your operating system:
128
129         "linux-x86_64"       Linux with AMD64 64-bit x86 instructions
130         "win-x86_64"         MS Windows with MS Visual C++ compiler
131         "darwin-x86_64"      Apple Mac OS X
132         "bluegeneq"          IBM's Blue Gene/Q
133         "cray{xe/xc}"        Cray's X-Series Supercomputer
134         "linux-ppc64le"      POWER/PowerPC
135
136
137 Your Charm++ version is made by concatenating the options, e.g.:
138
139 "netlrts-linux-x86_64"   Charm++ for a network of 64-bit Linux workstations,
140                          compiled using g++.
141
142 "gni-crayxc"             Charm++ for Cray XC systems using the system's compiler.
143
144
145 **** How to choose <options> ****
146
147 <version> above defines the most important OS, CPU and Communication of
148 your machine, and most of time it uses gcc as the default compiler.
149 To use a different compiler or demand additional special feature support, you
150 need to choose <options> from the following list:
151
152 * icc - Intel C/C++ compiler.
153 * ifort - Intel Fortran compiler
154 * xlc - IBM XLC compiler.
155 * clang - Clang compiler.
156 * mpicxx - Use MPI-wrappers for MPI builds.
157 * pgcc - Portland Group's C++ compiler.
158
159 * smp - Enable direct SMP support.  An "smp" version communicates using
160         shared memory within a machine; but normal message passing across
161         machines. Because of locking, "smp" may slightly impact non-SMP
162         performance. Try your application to decide if enabling smp mode
163         improves performance.
164
165 * tcp - for netlrts- version, default communication is via UDP. Using option
166         tcp will switch to TCP. TCP version of Charm++ is usually slower
167         than UDP, but it is more reliable.
168 * async - For Blue Gene/Q, this option enables use of hardware communication 
169           threads. For applications with significant communication on large
170           scale, this option typically improves performance.
171 * regularpages - on Cray systems, Charm++'s default is to use hugepages. This
172                  option disables hugepages, and uses regular malloc for messages.
173 * persistent - on Cray systems, this option enables use of persitent mode for
174                communication.
175 * pxshm - use Posix Shared Memory for communication between Charm++ processes
176           within a shared-memory host.
177 * syncft - enable in-memory fault tolerance support in Charm++.
178 * mlogft - enable message logging fault tolerance support in Charm++.
179 * tsan - compile Charm++ with support for Thread Sanitizer.
180 * papi - enable PAPI performance counters.
181 * ooc - build Charm++ with out-of-core execution features.
182 * bigsim - compile Charm++ as running on the BigSim emulator.
183
184 * help - show supported options for a version. For example, for netlrts-linux,
185          running:
186          > ./build charm++ netlrts-linux help
187          will give:
188 Supported compilers: clang craycc gcc icc iccstatic pgcc xlc xlc64
189 Supported options: bigemulator bigsim causalft clustermatic flang gfortran ifort local mlogft omp ooc papi persistent pgf90 pxshm scyld smp syncft sysvshm tcp tsan turing
190
191
192 BUILDING THE SOURCE
193 ===================
194
195 If you have downloaded a binary version of Charm++, you can skip
196 this step-- Charm++ should already be compiled.
197
198 Once you have decided on a version, unpack Charm++, cd into charm,
199 and run
200
201      > ./build <target> <version> <opts>
202
203 <target> is one of
204         "charm++"  The basic Charm++ language
205         "AMPI"     An implementation of MPI on top of Charm++
206         "LIBS"     Charm++, AMPI, and other libraries built on top of them
207         "Tau"      TAU's performance profiling/tracing
208
209 <version> is described above
210
211 <opts> are build-time options (such as the compiler or "smp"),
212 or command line options passed to the charmc compiler script.
213 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are
214 accepted.
215
216 For example, on a Linux machine, you would run
217      > ./build charm++ netlrts-linux-x86_64 -O
218
219 This will construct a netlrts-linux-x86_64 directory, link over all
220 the Charm++ source code into netlrts-linux-x86_64/tmp, build the entire
221 Charm++ runtime system in netlrts-linux-x86_64/tmp, and link example
222 programs into netlrts-linux-x86_64/examples.
223
224 Charm++ can be compiled with several optional features enabled or
225 disabled. These include runtime error checking, tracing, interactive
226 debugging, deterministic record-replay, and more. They can be
227 controlled by passing flags of the form --enable-featurename or
228 --disable-featurename to the build command:
229      > ./build charm++ netlrts-linux-x86_64 --disable-tracing
230
231 The list of optional features available is shown in the output of
232      > ./build --help
233
234 Production optimizations: Pass the configure option --with-production
235 to ./build to turn on optimizations in Charm++/Converse. This disables
236 most of the run-time checking performed by Converse and Charm++
237 runtime. This option should be used only after the program has been
238 debugged. Also, this option disables Converse/Charm++ tracing
239 mechanisms such as projections and summary.
240
241 Performance analysis: Pass the configuration option "--with-production 
242 --enable-tracing" to enable tracing and generation of logs for analysis with 
243 Projections. This is the recommended way to analyze performance of applications.
244
245 When Charm++ is built successfully, the directory structure under the
246 target directory will look like:
247
248 netlrts-linux-x86_64/
249    |
250    ---  benchmarks/             # benchmark programs
251    |
252    ---  bin/                    # all executables
253    |
254    ---  doc/                    # documentations
255    |
256    ---  include/                # header files
257    |
258    ---  lib/                    # libraries
259    |
260    ---  lib_so/                 # dynamic libraries
261    |
262    ---  examples/               # example programs
263    |
264    ---  tests/                  # test programs
265    |
266    ---  tmp/                    # Charm++ build directory
267
268
269 BUILDING A PROGRAM
270 ==================
271
272 To make a sample program, cd into examples/charm++/queens/.
273 This program solves the N-queens problem-- find how many ways there
274 are to arrange N queens on an NxN chess board such that none may
275 attack another.
276
277 To build the program, type make.  You should get an
278 executable named "pgm".
279
280
281 RUNNING A PROGRAM
282 ==================
283
284 Following the previous example, to run the program on two processors, type
285
286      > ./charmrun ./pgm 12 6 +p2
287
288 This should run for a few seconds, and print out:
289 There are 14200 Solutions to 12 queens. Finish time=4.030000
290
291 Charmrun is used to provide a uniform interface to run charm programs.
292 On some platforms, charmrun is just a shell script which calls the
293 platform-specific start program, such as mpirun on mpi versions.
294
295 For netlrts- version, charmrun is an executable which invokes ssh to start
296 node programs on remote machines. You should set up a ~/.nodelist that
297 enumerates all the machines you want to run jobs on, otherwise it will
298 create a default ~/.nodelist for you that contains only localhost. Here is a
299 typical .nodelist file:
300
301 group main ++shell /bin/ssh
302 host <machinename>
303
304 The default remote shell program is ssh, but you can define a different remote
305 shell to start remote processes using the ++shell option. You should
306 also make sure that ssh or your alternative can connect to these machines without
307 password authentication. Just type following command to verify:
308      > ssh <machinename> date
309 If this gives you current date immediately, your running environment with this
310 node has been setup correctly.
311
312 For development purposes, the netlrts- version of charmrun comes with an easy-to-use
313 "++local" option. No remote shell invocation is needed in this case. It starts
314 node programs right on your local machine. This could be useful if you just
315 want to run program on only one machine, for example, your laptop. This
316 can save you all the hassle of setting up ssh or charmd daemons.
317 To use this option, just type:
318
319      > ./charmrun ++local ./pgm 12 100 +p2
320
321 However, for best performance, you should launch one node program per processor.
322
323
324 BUILDING DYNAMIC LIBRARIES
325 ==========================
326
327 In order to compile Charm++ into dynamic libraries, one needs to specify the
328 "-build-shared" option to the Charm compiler script "charmc"
329 at link time. For example, to compile Charm++ under netlrts-linux/tmp, run
330
331      > make charm++ OPTS='-O -build-shared'
332
333 Charm++'s dynamic libraries are compiled into the lib_so/ directory.
334 Typically, they are generated with a ".so" suffix.
335
336 Note, "-build-shared" option is automatically turned on when building
337 Charm++ using the "build" script. So you don't need to pass "-build-shared"
338 option to "build".
339
340 One can compile a Charm++ application linking against Charm++ dynamic
341 libraries by linking with charmc's "-charm-shared" option.
342 For example:
343
344      > charmc -o pgm pgm.o -charm-shared
345
346 You can then run the program as usual.
347 Note, linking against Charm++ dynamic libraries produces much smaller size
348 binaries and takes much less linking time.
349
350
351 FOR MORE INFORMATION
352 ====================
353
354 The Charm++ web page, with documentation, more programs,
355 and the latest version of Charm++, is at
356         http://charm.cs.illinois.edu/
357
358 The Charm++ mailing list, for questions, comments, suggestions,
359 improvements, or bug reports is
360         charm@cs.illinois.edu
361
362
363 AUTHORS
364 =======
365
366 Charm++ was created and is maintained by the Parallel Programming Lab,
367 in the Computer Science department at the University of Illinois at
368 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
369 and staff have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
370 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
371 Gupta, Attila Gursoy, Nimish Shah, Sanjeev Krishnan, Jayant DeSouza,
372 Parthasarathy Ramachandran, Jeff Wright, Michael Lang, Jackie Wang,
373 Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan, Zehra Sura,
374 Krishnan Varadarajan, Sameer Paranjpye, Milind Bhandarkar, Robert Brunner,
375 Terry Wilmarth, Gengbin Zheng, Orion Lawlor, Celso Mendes, Karthik Mahesh,
376 Neelam Saboo, Greg Koenig, Sameer Kumar, Sayantan Chakravorty, Chao Huang,
377 Chee Lee, Fillipo Gioachin, Isaac Dooley, Abhinav Bhatele, Aaron Becker,
378 Ryan Mokos, Ramprasad Venkataraman, Gagan Gupta, Pritish Jetley, Lukasz
379 Wesolowski, Esteban Meneses, Chao Mei, David Kunzman, Osman Sarood,
380 Abhishek Gupta, Yanhua Sun, Ehsan Totoni, Akhil Langer, Cyril Bordage,
381 Harshit Dokania, Prateek Jindal, Jonathan Lifflander, Xiang Ni,
382 Harshitha Menon, Nikhil Jain, Vipul Harsh, Bilge Acun, Phil Miller,
383 Seonmyeong Bak, and Karthik Senthil. Current developers include Eric Bohm,
384 Ronak Buch, Michael Robson, Eric Mikida, Sam White, Juan Galvez, Nitin Bhat,
385 Kavitha Chandrasekar, Jaemin Choi, Matthias Diener, Evan Ramos,
386 Raghavendra Kanakagiri, and Venkatasubrahmanian Narayanan.
387