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