Update README and charmc year from 2018 to 2019
[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    ---  bin/                    # all executables
251    |
252    ---  doc/                    # documentations
253    |
254    ---  include/                # header files
255    |
256    ---  lib/                    # libraries
257    |
258    ---  lib_so/                 # dynamic libraries
259    |
260    ---  examples/               # all example programs
261    |
262    ---  tests/                  # all test programs
263    |
264    ---  tmp/                    # Charm++ build directory
265
266
267 BUILDING A PROGRAM
268 ==================
269
270 To make a sample program, cd into examples/charm++/queens/.
271 This program solves the N-queens problem-- find how many ways there
272 are to arrange N queens on an NxN chess board such that none may
273 attack another.
274
275 To build the program, type make.  You should get an
276 executable named "pgm".
277
278
279 RUNNING A PROGRAM
280 ==================
281
282 Following the previous example, to run the program on two processors, type
283
284      > ./charmrun ./pgm 12 6 +p2
285
286 This should run for a few seconds, and print out:
287 There are 14200 Solutions to 12 queens. Finish time=4.030000
288
289 Charmrun is used to provide a uniform interface to run charm programs.
290 On some platforms, charmrun is just a shell script which calls the
291 platform-specific start program, such as mpirun on mpi versions.
292
293 For netlrts- version, charmrun is an executable which invokes ssh to start
294 node programs on remote machines. You should set up a ~/.nodelist that
295 enumerates all the machines you want to run jobs on, otherwise it will
296 create a default ~/.nodelist for you that contains only localhost. Here is a
297 typical .nodelist file:
298
299 group main ++shell /bin/ssh
300 host <machinename>
301
302 The default remote shell program is ssh, but you can define a different remote
303 shell to start remote processes using the ++shell option. You should
304 also make sure that ssh or your alternative can connect to these machines without
305 password authentication. Just type following command to verify:
306      > ssh <machinename> date
307 If this gives you current date immediately, your running environment with this
308 node has been setup correctly.
309
310 For development purposes, the netlrts- version of charmrun comes with an easy-to-use
311 "++local" option. No remote shell invocation is needed in this case. It starts
312 node programs right on your local machine. This could be useful if you just
313 want to run program on only one machine, for example, your laptop. This
314 can save you all the hassle of setting up ssh or charmd daemons.
315 To use this option, just type:
316
317      > ./charmrun ++local ./pgm 12 100 +p2
318
319 However, for best performance, you should launch one node program per processor.
320
321
322 BUILDING DYNAMIC LIBRARIES
323 ==========================
324
325 In order to compile Charm++ into dynamic libraries, one needs to specify the
326 "-build-shared" option to the Charm compiler script "charmc"
327 at link time. For example, to compile Charm++ under netlrts-linux/tmp, run
328
329      > make charm++ OPTS='-O -build-shared'
330
331 Charm++'s dynamic libraries are compiled into the lib_so/ directory.
332 Typically, they are generated with a ".so" suffix.
333
334 Note, "-build-shared" option is automatically turned on when building
335 Charm++ using the "build" script. So you don't need to pass "-build-shared"
336 option to "build".
337
338 One can compile a Charm++ application linking against Charm++ dynamic
339 libraries by linking with charmc's "-charm-shared" option.
340 For example:
341
342      > charmc -o pgm pgm.o -charm-shared
343
344 You can then run the program as usual.
345 Note, linking against Charm++ dynamic libraries produces much smaller size
346 binaries and takes much less linking time.
347
348
349 FOR MORE INFORMATION
350 ====================
351
352 The Charm++ web page, with documentation, more programs,
353 and the latest version of Charm++, is at
354         http://charm.cs.illinois.edu/
355
356 The Charm++ mailing list, for questions, comments, suggestions,
357 improvements, or bug reports is
358         charm@cs.illinois.edu
359
360
361 AUTHORS
362 =======
363
364 Charm++ was created and is maintained by the Parallel Programming Lab,
365 in the Computer Science department at the University of Illinois at
366 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
367 and staff have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
368 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
369 Gupta, Attila Gursoy, Nimish Shah, Sanjeev Krishnan, Jayant DeSouza,
370 Parthasarathy Ramachandran, Jeff Wright, Michael Lang, Jackie Wang,
371 Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan, Zehra Sura,
372 Krishnan Varadarajan, Sameer Paranjpye, Milind Bhandarkar, Robert Brunner,
373 Terry Wilmarth, Gengbin Zheng, Orion Lawlor, Celso Mendes, Karthik Mahesh,
374 Neelam Saboo, Greg Koenig, Sameer Kumar, Sayantan Chakravorty, Chao Huang,
375 Chee Lee, Fillipo Gioachin, Isaac Dooley, Abhinav Bhatele, Aaron Becker,
376 Ryan Mokos, Ramprasad Venkataraman, Gagan Gupta, Pritish Jetley, Lukasz
377 Wesolowski, Esteban Meneses, Chao Mei, David Kunzman, Osman Sarood,
378 Abhishek Gupta, Yanhua Sun, Ehsan Totoni, Akhil Langer, Cyril Bordage,
379 Harshit Dokania, Prateek Jindal, Jonathan Lifflander, Xiang Ni,
380 Harshitha Menon, Nikhil Jain, Vipul Harsh, Bilge Acun, Phil Miller,
381 Seonmyeong Bak, and Karthik Senthil. Current developers include Eric Bohm,
382 Ronak Buch, Michael Robson, Eric Mikida, Sam White, Juan Galvez, Nitin Bhat,
383 Kavitha Chandrasekar, Jaemin Choi, Matthias Diener, Evan Ramos, and
384 Raghavendra Kanakagiri.
385