a fix in the previous commit
[charm.git] / doc / charisma / manual.tex
1 \documentclass[10pt]{article}
2 \usepackage{../pplmanual}
3 \input{../pplmanual}
4 \usepackage{fancyvrb}
5 \usepackage{shortvrb}
6
7 \def\smallfbox#1{{\small {\fbox{#1}}}}
8 \def\code#1{{\small {\tt {#1}}}}
9
10 \title{Charisma Manual}
11 \version{1.0}
12 \credits{
13 Charisma is an orchestration language authored by Laxmikant Kal\'{e}, Mark Hills,
14 Chao Huang and Pritish Jetley. It was developed by Chao Huang and is currently maintained by Pritish Jetley.
15 }
16
17 \begin{document}
18 \maketitle
19
20 \section{Introduction}
21
22 This manual describes Charisma, an orchestration language for migratable
23 parallel objects. 
24 Charisma can be downloaded from the CVS repository hosted on
25 \texttt{charm.cs.uiuc.edu}:
26
27 \begin{SaveVerbatim}{foodecl}
28   cvs co orchestration
29 \end{SaveVerbatim}
30 \smallfbox{\BUseVerbatim{foodecl}}
31
32
33 \section{Charisma Syntax}
34 A Charisma program is composed of two parts: the orchestration code in a .or
35 file, and sequential user code in C/C++ form. 
36
37 \subsection{Orchestration Code}
38 \input{orchcode}
39
40 \subsection{Sequential Code}
41 \label{sec:sequential}
42 \input{seqcode}
43
44 \section{Building and Running a Charisma Program}
45 There are two steps to build a Charisma program: generating Charm++ program 
46 from orchestration code, and building the Charm++ program. 
47
48 1) Charisma compiler, currently named \code{orchc}, is used to compile the
49 orchestration code (.or file) and integrate sequential code to generate a
50 Charm++ program. The resultant Charm++ program usually consists of the 
51 following code files: Charm++ Interface file ([modulename].ci), header file 
52 ([modulename].h) and C++ source code file ([modulename].C). The command 
53 for this step is as follows.
54
55 \begin{SaveVerbatim}{foodecl}
56     > orchc [modulename].or
57 \end{SaveVerbatim}
58 \smallfbox{\BUseVerbatim{foodecl}}
59
60 2) Charm++ compiler, charmc, is used to parse the Charm++ Interface (.ci) file,
61 compile C/C++ code, and link and build the executable. The typical commands are:
62 \begin{SaveVerbatim}{foodecl}
63     > charmc [modulename].ci
64     > charmc [modulename].C -c
65     > charmc [modulename].o -o pgm -language charm++
66 \end{SaveVerbatim}
67 \smallfbox{\BUseVerbatim{foodecl}}
68
69 Running the Charisma program is the same as running a Charm++ program, using
70 Charm++'s job launcher \code{charmrun}. (On some platforms like CSE's Turing 
71 Cluster, use the customized job launcher \code{rjq} or \code{rj}.) 
72
73 \begin{SaveVerbatim}{foodecl}
74     > charmrun pgm +p4
75 \end{SaveVerbatim}
76 \smallfbox{\BUseVerbatim{foodecl}}
77
78 Please refer to Charm++'s manual and tutorial for more details of building 
79 and running a Charm++ program. 
80
81 \section{Support for Library Module}
82 \label{sec:module}
83 \input{libmodule}
84
85 \section{Using Load Balancing Module}
86 \label{sec:ldb}
87 \input{ldb}
88
89 \section{Handling Sparse Object Arrays}
90 \label{sec:sparse}
91
92 In Charisma, when we declare an object array, by default a dense array is
93 created with all the elements populated. For instance, when we have the
94 following declaration in the orchestration code, an array of NxNxN is created. 
95 \begin{SaveVerbatim}{foodecl}
96     class Cell : ChareArray3D;
97     obj cells : Cell[N,N,N];
98 \end{SaveVerbatim}
99 \smallfbox{\BUseVerbatim{foodecl}}
100
101 There are certain occasions when the programmer may need sparse object arrays,
102 in which not all elements are created. An example is neighborhood force
103 calculation in molecular dynamics application. We have a 3D array of Cell
104 objects to hold the atom coordinates, and a 6D array of CellPair objects to
105 perform pairwise force calculation between neighboring cells. In this case, not
106 all elements in the 6D array of CellPair are necessary in the program. Only
107 those which represent two immediately neighboring cells are needed for the
108 force calculation. In this case, Charisma provides flexibility of declaring a
109 sparse object array, with a \code{sparse} keyword following the object array
110 declaration, as follows.
111
112 \begin{SaveVerbatim}{foodecl}
113     class CellPair : ChareArray6D;      
114     obj cellpairs : CellPair[N,N,N,N,N,N],sparse; 
115 \end{SaveVerbatim}
116 \smallfbox{\BUseVerbatim{foodecl}}
117
118 Then the programmer is expected to supply a sequential function with the name
119 \code{getIndex\_ARRAYNAME} to generate a list of selected indices of the
120 elements to create. As an example, the following function essentially tells the
121 system to generate all the NxNxNxNxNxN elements for the 6D array. 
122
123 \begin{SaveVerbatim}{foodecl}
124   void getIndex_cellpairs(CkVec<CkArrayIndex6D>& vec){
125     int i,j,k,l,m,n;
126     for(i=0;i<N;i++)
127       for(j=0;j<N;j++)
128         for(k=0;k<N;k++)
129           for(l=0;l<N;l++)
130             for(m=0;m<N;m++)
131               for(n=0;n<N;n++)
132                 vec.push_back(CkArrayIndex6D(i,j,k,l,m,n));
133   }
134 \end{SaveVerbatim}
135
136 \smallfbox{\BUseVerbatim{foodecl}}
137
138
139 %neighbors and neighborsize for dense array
140
141 \appendix
142 \label{sec:appendix}
143 \input{example}
144 \end{document}