Created for 5.5 release.
[charm.git] / README
1                               Charm++ 5.5
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 PICKING A VERSION
15 =================
16
17 First, you need to decide which version of charm++ to use.  Your
18 choice is determined by three options:
19
20 1.)  The way a parallel program written in Charm++ will communicate:
21
22         "net-" Charm++ communicates using the regular TCP/IP stack
23 (UDP packets), which works everywhere but is fairly slow.  Use this
24 option for networks of workstations, clusters, or single-machine 
25 development and testing.
26
27         "mpi-" Charm++ communicates using MPI calls.  Use this for
28 machines with a good MPI implementation (such as the Origin 2000).
29
30         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
31 communicates using direct calls to the machine's communication primitives.
32
33         "sim-" and "uth-" are not actively maintained.  These are
34 single-processor versions: "uth-" simulates processors as user-level
35 threads; "sim-" switches between processors and counts communications.
36
37
38 2.)  Your operating system:
39
40         "linux"   Linux 
41         "win32"   MS Windows NT/98/2k (and MS Visual C++ compiler)
42         "cygwin"  MS Windows with Cygnus' Cygwin Unix layer
43         "irix"    SGI IRIX
44         "origin"  SGI Origin 2000 IRIX
45         "sol"     Solaris
46         "sun"     SunOS
47         "rs6k"    IBM R/S 6000 A/IX 
48         "sp"      IBM SP A/IX
49         "hp"      Hewlett-Packard HP-UX
50         "axp"     DEC Alpha DECUNIX
51         
52
53 3.)  Your compiler and other options.  Charm++ normally picks an
54 appropriate compiler for the system, but you may select another
55 compiler:
56
57         "-cc"      The OEM C/C++ compiler.  When given, this
58 will override the choice of the GNU C/C++ compiler.
59         "-kcc"     Kuck & Associates C++ compiler.
60         "-acc"     Uses HP's aCC instead of CC.
61
62 Some operating systems have other options, such as:
63         "-x86"     For Solaris, use PC hardware (instead of Sun).
64         "-axp"     For Linux, use Alpha hardware (instead of PC).
65         "-64"      For IRIX, use -64 instead of -32. 
66
67 You may also choose to enable direct SMP support with a "-smp"
68 version, which may result in more efficient communication in
69 a cluster-of-SMPs.  A "-smp" version will communicate using
70 shared memory within a machine; but message passing across machines.
71 "-smp" is currently only available with "net-" versions.
72 Because of locking, "-smp" may slightly impact non-SMP performance.
73
74
75 Your Charm++ version is made by concatenating all three options, e.g.:
76
77 "net-linux"     Charm++ for a network of Linux workstations, compiled
78                 using g++.
79 "net-linux-kcc" Charm++ for a network of Linux workstations, compiled
80                 using Kuck & Associates C++ compiler.
81 "net-linux-smp" Charm++ for a network of Linux SMP workstations,
82                 compiled using g++.
83 "net-sol-cc"    Charm++ for a network of Sun workstations, 
84                 compiled using Sun CC.
85 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
86
87
88
89 BUILDING THE SOURCE
90 ===================
91
92 If you have downloaded a binary version of Charm++, you can skip
93 this step-- Charm++ should already be compiled.  For win32 systems,
94 see README.win32; for net- version, see README.net
95
96 Once you have decided on a version, unpack Charm++, cd into charm,
97 and run
98
99      > ./SUPER_INSTALL _target_ _version_
100
101 Where _target_ is one of
102         "charm++"  The basic Charm++ language.
103         "AMPI"     An implementation of MPI on top of Charm++
104         "FEM"      A Finite-Element framework on top of Charm++
105
106 For example, on a Linux machine, you would run
107      > ./SUPER_INSTALL charm++ net-linux
108
109
110 This will construct a _version_ directory, link over all
111 the Charm++ source code into _version_/tmp, build the entire
112 Charm++ runtime system in _version_/tmp, and link sample programs 
113 into _version_/pgms.
114
115
116
117 BUILDING A PROGRAM
118 ==================
119
120 To make a sample program, cd into _version_/pgms/charm++/queens/.
121 This program solves the N-queens problem-- find how many ways there 
122 are to arrange N queens on an NxN chess board such that none may 
123 attack another.  
124
125 To build the program, type make.  You should get an
126 executable named "pgm".
127
128 To run the program on two processors, type
129      > ./charmrun pgm 12 100 +p2
130
131 This should run for a few seconds, and print out:
132 There are 14200 Solutions to 12 queens. Finish time=4.030000
133
134
135
136 FOR MORE INFORMATION
137 ====================
138
139 The Charm++ web page, with documentation, more programs,
140 and the latest version of Charm++, is at
141         http://charm.cs.uiuc.edu/
142
143 The Charm++ mailing list, for questions, comments, suggestions, 
144 improvements, or bug reports is
145         ppl@cs.uiuc.edu
146
147
148 AUTHORS
149 =======
150
151 Charm++ is written and maintained by the Parallel Programming
152 Lab, in the Computer Science department at the University of 
153 Illinois at Urbana-Champaign.  Our managing professor is
154 Dr. L.V. Kale; students have included (in rough time order)
155 Wennie Shu, Kevin Nomura, Wayne Fenton, Balkrishna Ramkumar,
156 Vikram Saletore, Amitabh B. Sinha, Manish Gupta, Attila Gursoy, 
157 Balkrishna Ramkumar, Amitabh B. Sinha, Nimish Shah, Sanjeev 
158 Krishnan, Parthasarathy Ramachandran, Jeff Wright, Michael Lang, 
159 Jackie Wang, Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan,
160 Zehra Sura, Krishnan Varadarajan, and Sameer Paranjpye.  Current developers
161 include Milind Bhandarkar, Robert Brunner, Terry Wilmarth, Gengbin Zheng, 
162 Jayant Desouza, Orion Lawlor, Karthik Mahesh, and Neelam Saboo.