doc: clean up syntax highlighting
[charm.git] / doc / charisma / manual.rst
1 ========
2 Charisma
3 ========
4
5 .. contents::
6    :depth: 3
7
8 Introduction
9 ============
10
11 This manual describes Charisma, an orchestration language for migratable
12 parallel objects. Charisma can be downloaded from
13 https://charm.cs.illinois.edu/gerrit/gitweb?p=Charisma.git
14
15 Charisma Syntax
16 ===============
17
18 A Charisma program is composed of two parts: the *orchestration* code in a
19 **.or** file, and sequential user code in C/C++ form.
20
21 Orchestration Code
22 ------------------
23
24 The orchestration code in the .or file can be divided into two parts. The
25 header part contains information about the program, included external
26 files, defines, and declaration of parallel constructs used in the code.
27 The orchestration section is made up of statements that form a global
28 control flow of the parallel program. In the orchestration code,
29 Charisma employs a macro dataflow approach; the statements produce and
30 consume values, from which the control flows can be organized, and
31 messages and method invocations generated.
32
33 Header Section
34 ~~~~~~~~~~~~~~
35
36 The very first line should give the name of the Charisma program with
37 the ``program`` keyword.
38
39 .. code-block:: pascal
40
41        program jacobi
42
43 The ``program`` keyword can be replaced with ``module``, which means
44 that the output program is going to be a library module instead of a
45 stand-alone program. Please refer to Section :numref:`secmodule` for
46 more details.
47
48 Next, the programmer can include external code files in the generated
49 code with the keyword ``include`` specifying the filename without extension. For
50 example, the following statement tells the Charisma compiler to look for
51 header file "particles.h" to be included in the generated header file
52 "jacobi.h" and to look for C/C++ code file "particles.[C | cc | cpp | cxx | c]"
53 to be included in the generated C++ code file "jacobi.C".
54
55 .. code-block:: pascal
56
57        include particles;
58
59 It is useful when there is source code that must precede the generated
60 parallel code, such as basic data structure declaration.
61
62 After the ``include`` section is the ``define`` section, where
63 environmental variables can be defined for Charisma. For example, to
64 tell Charisma to generate additional code to enable the load balancing
65 module, the programmer needs to use ``define ldb;`` in the orchestration code.
66 Please refer to Section :numref:`secldb` for details.
67
68 Declaration Section
69 ~~~~~~~~~~~~~~~~~~~
70
71 Next comes the declaration section, where classes, objects and
72 parameters are declared. A Charisma program is composed of multiple sets
73 of parallel objects which are organized by the orchestration code.
74 Different sets of objects can be instantiated from different class
75 types. Therefore, we have to specify the class types and object
76 instantiation. Also we need to specify the parameters (See
77 Section :numref:`sec:orchsec`) to use in the orchestration
78 statements.
79
80 A Charisma program or module has one "MainChare" class, and it does not
81 require explicit instantiation since it is a singleton. The statement to
82 declare MainChare looks like this:
83
84 .. code-block:: c++
85
86        class JacobiMain : MainChare;
87
88 For object arrays, we first need to declare the class types inherited
89 from 1D object array, 2D object array, etc, and then instantiate from
90 the class types. The dimensionality information of the object array is
91 given in a pair of brackets with each dimension size separated by a
92 comma.
93
94 .. code-block:: c++
95
96        class JacobiWorker : ChareArray1D;
97        obj workers : JacobiWorker[N];
98
99        class Cell : ChareArray3D;
100        obj cells : Cell[M,M,M];
101
102 Note that key word ``class`` is for class type derivation, and ``obj`` is
103 for parallel object or object array instantiation. The above code
104 segment declares a new class type ``JacobiWorker`` which is a 1D object
105 array, and the programmer is supposed to supply sequential code for it
106 in files ``JacobiWorker.h`` and ``JacobiWorker.C`` (see
107 Section :numref:`sec:sequential` for more details on sequential
108 code). Object array ``workers`` is instantiated from ``JacobiWorker`` and
109 has 16 elements.
110
111 The last part is orchestration parameter declaration. These parameters
112 are used only in the orchestration code to connect input and output of
113 orchestration statements, and their data type and size is declared here.
114 More explanation of these parameters can be found in
115 Section :numref:`sec:orchsec`.
116
117 .. code-block:: pascal
118
119        param lb : double[N];
120        param rb : double[N];
121
122 With this, ``lb`` and ``rb`` are declared as parameters that can be
123 "connected" with local variables of double array of size of 512.
124
125 .. _sec:orchsec:
126
127 Orchestration Section
128 ~~~~~~~~~~~~~~~~~~~~~
129
130 In the main body of orchestration code, the programmer describes the
131 behavior and interaction of the elements of the object arrays using
132 orchestration statements.
133
134 :math:`\bullet` **Foreach Statement**
135
136 The most common kind of parallelism is the invocation of a method across
137 all elements in an object array. Charisma provides a ``foreach`` statement
138 for specifying such parallelism. The keywords ``foreach`` and
139 ``end-foreach`` forms an enclosure within which the parallel invocation
140 is performed. The following code segment invokes the entry method
141 ``compute`` on all the elements of array ``myWorkers``.
142
143 .. code-block:: c#
144
145      foreach i in workers
146        workers[i].compute();
147      end-foreach
148
149 :math:`\bullet` **Publish Statement and Produced/Consumed Parameters**
150
151 In the orchestration code, an object method invocation can have input
152 and output (consumed and produced) parameters. Here is an orchestration
153 statement that exemplifies the input and output of this object methods
154 ``workers.produceBorders`` and ``workers.compute``.
155
156 .. code-block:: c#
157
158      foreach i in workers
159        (lb[i], rb[i]) <- workers[i].produceBorders();
160        workers[i].compute(lb[i+1], rb[i-1]);
161
162        (+error) <- workers[i].reduceData();
163      end-foreach
164
165 Here, the entry method ``workers[i].produceBorders`` produces (called
166 *published* in Charisma) values of ``lb[i], rb[i]``, enclosed in a pair
167 of parentheses before the publishing sign ``<-``. In the second
168 statement, function ``workers[i].compute`` consumes values of
169 ``lb[i+1], rb[i-1]``, just like normal function parameters. If a
170 reduction operation is needed, the reduced parameter is marked with a
171 ``+`` before it, like the ``error`` in the third statement.
172
173 An entry method can have arbitrary number of published (produced and
174 reduced) values and consumed values. In addition to basic data types,
175 each of these values can also be an object of arbitrary type. The values
176 published by ``A[i]`` must have the index ``i``, whereas values consumed
177 can have the index ``e(i)``, which is an index expression in the form of
178 ``i``\ :math:`\pm c` where :math:`c` is a constant. Although we have
179 used different symbols (``p`` and ``q``) for the input and the output
180 variables, they are allowed to overlap.
181
182 The parameters are produced and consumed in the program order. Namely, a
183 parameter produced in an early statement will be consumed by the next
184 consuming statement, but will no longer be visible to any consuming
185 statement after a subsequent statement producing the same parameter in
186 program order. Special rules involving loops are discussed later with
187 loop statement.
188
189 :math:`\bullet` **Overlap Statement**
190
191 Complicated parallel programs usually have concurrent flows of control.
192 To explicitly express this, Charisma provides a ``overlap`` keyword,
193 whereby the programmer can fire multiple overlapping control flows.
194 These flows may contain different number of steps or statements, and
195 their execution should be independent of one another so that their
196 progress can interleave with arbitrary order and always return correct
197 results.
198
199 .. code-block:: c#
200
201      overlap
202      {
203        foreach i in workers1
204          (lb[i], rb[i]) <- workers1[i].produceBorders();
205        end-foreach
206        foreach i in workers1
207          workers1[i].compute(lb[i+1], rb[i-1]);
208        end-foreach
209      }
210      {
211        foreach i in workers2
212          (lb[i], rb[i]) <- workers2[i].compute(lb[i+1], rb[i-1]);
213        end-foreach
214      }
215      end-overlap
216
217 This example shows an ``overlap`` statement where two blocks in curly
218 brackets are executed in parallel. Their execution joins back to one at
219 the end mark of ``end-overlap``.
220
221 :math:`\bullet` **Loop Statement**
222
223 Loops are supported with ``for`` statement and ``while`` statement. Here
224 are two examples.
225
226 .. code-block:: pascal
227
228      for iter = 0 to MAX_ITER
229         workers.doWork();
230      end-for
231
232 .. code-block:: pascal
233
234      while (err > epsilon)
235         (+err) <- workers.doWork();
236         MainChare.updateError(err);
237      end-while
238
239 The loop condition in ``for`` statement is independent from the main
240 program; it simply tells the program to repeat the block for so many
241 times. The loop condition in ``while`` statement is actually updated in
242 the MainChare. In the above example, ``err`` and ``epsilon`` are both
243 member variables of class ``MainChare``, and can be updated as the
244 example shows. The programmer can activate the "autoScalar" feature by
245 including a ``define autoScalar;`` statement in the orchestration
246 code. When autoScalar is enabled, Charisma will find all the scalars in
247 the ``.or`` file, and create a local copy in the ``MainChare``. Then
248 every time the scalar is published by a statement, an update statement
249 will automatically be inserted after that statement. The only thing that
250 the programmer needs to do is to initialize the local scalar with a
251 proper value.
252
253 Rules of connecting produced and consumed parameters concerning loops
254 are natural. The first consuming statement will look for values produced
255 by the last producing statement before the loop, for the first
256 iteration. The last producing statement within the loop body, for the
257 following iterations. At the last iteration, the last produced values
258 will be disseminated to the code segment following the loop body. Within
259 the loop body, program order holds.
260
261 .. code-block:: c#
262
263      for iter = 1 to MAX_ITER
264        foreach i in workers
265          (lb[i], rb[i]) <- workers[i].compute(lb[i+1], rb[i-1]);
266        end-foreach
267      end-for
268
269 One special case is when one statement's produced parameter and consumed
270 parameter overlaps. It must be noted that there is no dependency within
271 the same ``foreach`` statement. In the above code segment, the values
272 consumed ``lb[i], rb[i]`` by ``worker[i]`` will not come from its
273 neighbors in this iteration. The rule is that the consumed values always
274 originate from previous ``foreach`` statements or ``foreach`` statements
275 from a previous loop iteration, and the published values are visible
276 only to following ``foreach`` statements or ``foreach`` statements in
277 following loop iterations.
278
279 :math:`\bullet` **Scatter and Gather Operation**
280
281 A collection of values produced by one object may be split and consumed
282 by multiple object array elements for a scatter operation. Conversely, a
283 collection of values from different objects can be gathered to be
284 consumed by one object.
285
286 .. code-block:: c#
287
288      foreach i in A
289        (points[i,*]) <- A[i].f(...);
290      end-foreach
291      foreach k,j in B
292        (...) <- B[k,j].g(points[k,j]);
293      end-foreach
294
295 A wildcard dimension ``*`` in ``A[i].f()``'s output ``points``
296 specifies that it will publish multiple data items. At the consuming
297 side, each ``B[k,j]`` consumes only one point in the data, and therefore
298 a scatter communication will be generated from ``A`` to ``B``. For
299 instance, ``A[1]`` will publish data ``points[1,0..N-1]`` to be consumed
300 by multiple array objects ``B[1,0..N-1]``.
301
302 .. code-block:: none
303
304      foreach i,j in A
305        (points[i,j]) <- A[i,j].f(...);
306      end-foreach
307      foreach k in B
308        (...) <- B[k].g(points[*,k]);
309      end-foreach
310
311 Similar to the scatter example, if a wildcard dimension ``*`` is in the
312 consumed parameter and the corresponding published parameter does not
313 have a wildcard dimension, there is a gather operation generated from
314 the publishing statement to the consuming statement. In the following
315 code segment, each ``A[i,j]`` publishes a data point, then data points
316 from ``A[0..N-1,j]`` are combined together to for the data to be
317 consumed by ``B[j]``.
318
319 Many communication patterns can be expressed with combination of
320 orchestration statements. For more details, please refer to PPL
321 technical report 06-18, "Charisma: Orchestrating Migratable Parallel
322 Objects".
323
324 Last but not least, all the orchestration statements in the ``.or`` file
325 together form the dependency graph. According to this dependency graph,
326 the messages are created and the parallel program progresses. Therefore,
327 the user is advised to put only parallel constructs that are driven by
328 the data dependency into the orchestration code. Other elements such as
329 local dependency should be coded in the sequential code.
330
331 .. _sec:sequential:
332
333 Sequential Code
334 ---------------
335
336 Sequential Files
337 ~~~~~~~~~~~~~~~~
338
339 The programmer supplies the sequential code for each class as necessary.
340 The files should be named in the form of class name with appropriate
341 file extension. The header file is not really an ANSI C header file.
342 Instead, it is the sequential portion of the class's declaration.
343 Charisma will generate the class declaration from the orchestration
344 code, and incorporate the sequential portion in the final header file.
345 For example, if a molecular dynamics simulation has the following
346 classes (as declared in the orchestration code):
347
348 .. code-block:: c++
349
350        class MDMain : MainChare;
351        class Cell : ChareArray3D;
352        class CellPair : ChareArray6D;
353
354 The user is supposed to prepare the following sequential files for the
355 classes: ``MDMain.h``, ``MDMain.C``, ``Cell.h``, ``Cell.C``, ``CellPair.h`` and ``CellPair.C``,
356 unless a class does not need sequential declaration and/or definition
357 code. Please refer to the example in the Appendix.
358
359 For each class, a member function ``void initialize(void)`` can be defined
360 and the generated constructor will automatically call it. This saves the
361 trouble of explicitly call initialization code for each array object.
362
363 Producing and Consuming Functions
364 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365
366 The C/C++ source code is nothing different than ordinary sequential
367 source code, except for the producing/consuming part. For consumed
368 parameters, a function treats them just like normal parameters passed in.
369 To handle produced parameters, the sequential code needs to do two
370 special things. First, the function should have an extra parameter for
371 output parameters. The parameter type is keyword ``outport``, and the
372 parameter name is the same as appeared in the orchestration code.
373 Second, in the body of the function, the keyword ``produce`` is used to
374 connect the orchestration parameter and the local variables whose value
375 will be sent out, in a format of a function call, as follows.
376
377 .. code-block:: c++
378
379        produce(produced_parameter, local_variable[, size_of_array]);
380
381 When the parameter represents a data array, we need the additional
382 ``size_of_array`` to specify the size of the data array.
383
384 The dimensionality of an orchestration parameter is divided into two
385 parts: its dimension in the orchestration code, which is implied by the
386 dimensionality of the object arrays the parameter is associated, and the
387 local dimensionality, which is declared in the declaration section. The
388 orchestration dimension is not explicitly declared anywhere, but it is
389 derived from the object arrays. For instance, in the 1D Jacobi worker
390 example, ``lb`` and ``rb`` has the same orchestration dimensionality of
391 workers, namely 1D of size 16. The local dimensionality is used when
392 the parameter is associated with local variables in sequential code.
393 Since ``lb`` and ``rb`` are declared to have the local type and dimension of
394 ``double [512]``, the producing statement should connect it with a local
395 variable of ``double [512]``.
396
397 .. code-block:: c++
398
399        void JacobiWorker::produceBorders(outport lb, outport rb) {
400          ...
401          produce(lb, localLB, 512);
402          produce(rb, localRB, 512);
403        }
404
405 Special cases of the produced/consumed parameters involve scatter/gather
406 operations. In scatter operation, since an additional dimension is
407 implied in the produced parameter, we the ``local_variable`` should have
408 additional dimension equal to the dimension over which the scatter is
409 performed. Similarly, the input parameter in gather operation will have
410 an additional dimension the same size of the dimension of the gather
411 operation.
412
413 For reduction, one additional parameter of type ``char[]`` is added to
414 specify the reduction operation. Built-in reduction operations are ``+``
415 (sum), ``*`` (product), ``<`` (minimum), ``>`` (maximum) for
416 basic data types. For instance the following statements takes the sum of
417 all local value of ``result`` and for output in ``sum``.
418
419 .. code-block:: c++
420
421        reduce(sum, result, "+");
422
423 If the data type is a user-defined class, then you might use the
424 function or operator defined to do the reduction. For example, assume we
425 have a class called ``Force``, and we have an ``add`` function (or a ``+``
426 operator) defined.
427
428 .. code-block:: c++
429
430        Force& Force::add(const Force& f);
431
432 In the reduction to sum all the local forces, we can use
433
434 .. code-block:: c++
435
436        reduce(sumForces, localForce, "add");
437
438 Miscellaneous Issues
439 ~~~~~~~~~~~~~~~~~~~~
440
441 In sequential code, the user can access the object's index by a keyword
442 ``thisIndex``. The index of 1-D to 6-D object arrays are:
443
444 .. code-block:: c#
445
446      1D: thisIndex
447      2D: thisIndex.{x,y}
448      3D: thisIndex.{x,y,z}
449      4D: thisIndex.{w,x,y,z}
450      5D: thisIndex.{v,w,x,y,z}
451      6D: thisIndex.{x1,y1,z1,x2,y2,z2}
452
453 Building and Running a Charisma Program
454 =======================================
455
456 There are two steps to build a Charisma program: generating Charm++
457 program from orchestration code, and building the Charm++ program.
458
459 1) Charisma compiler, currently named ``orchc``, is used to compile the
460 orchestration code (``.or`` file) and integrate sequential code to generate
461 a Charm++ program. The resultant Charm++ program usually consists of the
462 following code files: Charm++ Interface file (``[modulename].ci``), header
463 file (``[modulename].h``) and C++ source code file (``[modulename].C``). The
464 command for this step is as follows.
465
466 .. code-block:: bash
467
468    $ orchc [modulename].or
469
470 2) Charm++ compiler, ``charmc``, is used to parse the Charm++ Interface
471 (``.ci``) file, compile C/C++ code, and link and build the executable. The
472 typical commands are:
473
474 .. code-block:: bash
475
476    $ charmc [modulename].ci
477    $ charmc [modulename].C -c
478    $ charmc [modulename].o -o pgm -language charm++
479
480 Running the Charisma program is the same as running a Charm++ program,
481 using Charm++'s job launcher ``charmrun`` (on some platforms like CSE's
482 Turing Cluster, use the customized job launcher ``rjq`` or ``rj``).
483
484 .. code-block:: bash
485
486    $ charmrun pgm +p4
487
488 Please refer to Charm++'s manual and tutorial for more details of
489 building and running a Charm++ program.
490
491 .. _secmodule:
492
493 Support for Library Module
494 ==========================
495
496 Charisma is capable of producing library code for reuse with another
497 Charisma program. We explain this feature in the following section.
498
499 Writing Module Library
500 ======================
501
502 The programmer uses the keyword ``module`` instead of ``program`` in the
503 header section of the orchestration code to tell the compiler that it is
504 a library module. Following keyword ``module`` is the module name, then
505 followed by a set of configuration variables in a pair parentheses. The
506 configuration variables are used in creating instances of the library,
507 for such info as problem size.
508
509 Following the first line, the library's input and output parameters are
510 posted with keywords ``inparam`` and ``outparam``.
511
512 .. code-block:: c++
513
514      module FFT3D(CHUNK, M, N);
515      inparam indata;
516      outparam outdata1, outdata2;
517
518 The body of the library is not very different from that of a normal
519 program. It takes input parameters and produces out parameters, as
520 posted in the header section.
521
522 Using Module Library
523 ====================
524
525 To use a Charisma module library, the programmer first needs to create
526 an instance of the library. There are two steps: including the module
527 and creating an instance.
528
529 .. code-block:: c++
530
531      use FFT3D;
532      library f1 : FFT3D(CHUNK=10, M=10, N=100);
533      library f2 : FFT3D(CHUNK=8, M=8, N=64);
534
535 The keyword ``use`` and the module name includes the module in the
536 program, and the keyword ``library`` creates an instance with the
537 instance name, followed by the module name with value assignment of
538 configuration variables. These statements must appear in the declaration
539 section before the library instance can be used in the main program's
540 orchestration code.
541
542 Invoking the library is like calling a publish statement; the input and
543 output parameters are the same, and the object name and function name
544 are replaced with the library instance name and the keyword ``call``
545 connected with a colon.
546
547 .. code-block:: c++
548
549      (f1_outdata[*]) <- f1:call(f1_indata[*]);
550
551 Multiple instances can be created out of the same module. Their
552 execution can interleave without interfering with one another.
553
554 .. _secldb:
555
556 Using Load Balancing Module
557 ===========================
558
559 Coding
560 ------
561
562 To activate the load balancing module and prepare objects for migration,
563 there are 3 things that need to be added in Charisma code.
564
565 First, the programmer needs to inform Charisma about load balancing
566 with a ``define ldb;`` statement in the header section of the
567 orchestration code. This will make Charisma generate extra Charm++ code
568 to do load balancing such as ``PUP`` methods.
569
570 Second, the user has to provide a ``PUP`` function for each class with
571 sequential data that needs to be moved when the object migrates. When
572 choosing which data items to pup, the user has the flexibility to
573 leave the dead data behind to save on communication overhead in
574 migration. The syntax for the sequential ``PUP`` is similar to that in a
575 Charm++ program. Please refer to the load balancing section in Charm++
576 manual for more information on ``PUP`` functions. A typical example
577 would look like this in user's sequential ``.C`` file:
578
579 .. code-block:: c++
580
581      void JacobiWorker::sequentialPup(PUP::er& p){
582        p|myLeft; p|myRight; p|myUpper; p|myLower;
583        p|myIter;
584        PUParray(p, (double *)localData, 1000);
585      }
586
587 Thirdly, the user will make the call to invoke load balancing session in
588 the orchestration code. The call is ``AtSync();`` and it is invoked on
589 all elements in an object array. The following example shows how to
590 invoke load balancing session every 4th iteration in a for-loop.
591
592 .. code-block:: c#
593
594      for iter = 1 to 100
595        // work work
596        if (iter % 4 == 0) then
597          foreach i in workers
598            workers[i].AtSync();
599          end-foreach
600        end-if
601      end-for
602
603 If a while-loop is used instead of for-loop, then the test-condition in
604 the ``if`` statement is a local variable in the program's MainChare. In
605 the sequential code, the user can maintain a local variable called
606 ``iter`` in MainChare and increment it every iteration.
607
608 Compiling and Running
609 ---------------------
610
611 Unless linked with load balancer modules, a Charisma program will not
612 perform actual load balancing. The way to link in a load balancer module
613 is adding ``-module EveryLB`` as a link-time option.
614
615 At run-time, the load balancer is specified in command line after the
616 ``+balancer`` option. If the balancer name is incorrect, the job
617 launcher will automatically print out all available load balancers. For
618 instance, the following command uses ``RefineLB``.
619
620 .. code-block:: bash
621
622    $ ./charmrun ./pgm +p16 +balancer RefineLB
623
624 .. _secsparse:
625
626 Handling Sparse Object Arrays
627 =============================
628
629 In Charisma, when we declare an object array, by default a dense array
630 is created with all the elements populated. For instance, when we have
631 the following declaration in the orchestration code, an array of NxNxN
632 is created.
633
634 .. code-block:: c#
635
636        class Cell : ChareArray3D;
637        obj cells : Cell[N,N,N];
638
639 There are certain occasions when the programmer may need sparse object
640 arrays, in which not all elements are created. An example is
641 neighborhood force calculation in molecular dynamics application. We
642 have a 3D array of Cell objects to hold the atom coordinates, and a 6D
643 array of CellPair objects to perform pairwise force calculation between
644 neighboring cells. In this case, not all elements in the 6D array of
645 CellPair are necessary in the program. Only those which represent two
646 immediately neighboring cells are needed for the force calculation. In
647 this case, Charisma provides flexibility of declaring a sparse object
648 array, with a ``sparse`` keyword following the object array declaration,
649 as follows.
650
651 .. code-block:: c#
652
653        class CellPair : ChareArray6D;
654        obj cellpairs : CellPair[N,N,N,N,N,N],sparse;
655
656 Then the programmer is expected to supply a sequential function with the
657 name ``getIndex_ARRAYNAME`` to generate a list of selected indices of
658 the elements to create. As an example, the following function
659 essentially tells the system to generate all the NxNxNxNxNxN elements
660 for the 6D array.
661
662 .. code-block:: c++
663
664      void getIndex_cellpairs(CkVec<CkArrayIndex6D>& vec) {
665        int i,j,k,l,m,n;
666        for(i=0;i<N;i++)
667          for(j=0;j<N;j++)
668            for(k=0;k<N;k++)
669              for(l=0;l<N;l++)
670                for(m=0;m<N;m++)
671                  for(n=0;n<N;n++)
672                    vec.push_back(CkArrayIndex6D(i,j,k,l,m,n));
673      }
674
675
676 Example: Jacobi 1D
677 ==================
678
679 Following is the content of the orchestration file ``jacobi.or``.
680
681 .. code-block:: c#
682
683    program jacobi
684
685    class  JacobiMain : MainChare;
686    class  JacobiWorker : ChareArray1D;
687    obj  workers : JacobiWorker[M];
688    param  lb : double[N];
689    param  rb : double[N];
690
691    begin
692        for iter = 1 to MAX_ITER
693         foreach i in workers
694             (lb[i], rb[i]) <- workers[i].produceBorders();
695             workers[i].compute(lb[i+1], rb[i-1]);
696         end-foreach
697        end-for
698    end
699
700 The class ``JacobiMain`` does not need any sequential code, so the only
701 sequential code are in ``JacobiWorker.h`` and ``JacobiWorker.C``. Note that
702 ``JacobiWorker.h`` contains only the sequential portion of JacobiWorker's
703 declaration.
704
705 .. code-block:: c++
706
707    #define N 512
708    #define M 16
709
710    int currentArray;
711    double localData[2][M][N];
712    double localLB[N];
713    double localRB[N];
714    int myLeft, myRight, myUpper, myLower;
715
716    void initialize();
717    void compute(double lghost[], double rghost[]);
718    void produceBorders(outport lb, outport rb);
719    double abs(double d);
720
721 Similarly, the sequential C code will be integrated into the generated C
722 file. Below is part of the sequential C code taken from ``JacobiWorker.C``
723 to show how consumed parameters (``rghost`` and ``lghost`` in
724 ``JacobiWorker::compute``) and produced parameters (``lb`` and ``rb`` in
725 ``JacobiWorker::produceBorders``) are handled.
726
727 .. code-block:: c++
728
729    void JacobiWorker::compute(double rghost[], double lghost[]) {
730        /* local computation for updating elements*/
731    }
732
733    void JacobiWorker::produceBorders(outport lb, outport rb) {
734        produce(lb, localData[currentArray][myLeft], myLower-myUpper+1);
735        produce(rb, localData[currentArray][myRight], myLower-myUpper+1);
736    }
737
738 The user compile these input files with the following command:
739
740 .. code-block:: bash
741
742    $ orchc jacobi.or
743
744 The compiler generates the parallel code for sending out messages,
745 organizing flow of control, and then it looks for sequential code files
746 for the classes declared, namely ``JacobiMain`` and ``JacobiWorker``,
747 and integrates them into the final output: ``jacobi.h``, ``jacobi.C``
748 and ``jacobi.ci``, which is a Charm++ program and can be built the way a
749 Charm++ program is built.