*** empty log message ***
[charm.git] / doc / f90charm / manual.tex
1 \documentclass[11pt]{article}
2
3 \newif\ifpdf
4 \ifx\pdfoutput\undefined
5   \pdffalse
6 \else
7   \pdfoutput=1
8   \pdftrue
9 \fi
10
11 \ifpdf
12   \pdfcompresslevel=9
13   \usepackage[pdftex,colorlinks=true,plainpages=false]{hyperref}
14 \else
15 \fi
16
17 \pagestyle{headings}
18
19 \title{Fortran90 Bindings for Charm++}
20 \author{Jayant Desouza}
21
22 \begin{document}
23
24 \maketitle
25
26 To interface Fortran90 to Charm and thus obtain a parallel version of
27 your program you need to do the following things:
28 \begin{enumerate}
29 \item Write your F90 program with some constraints
30 \item Write a Charm Interface file (extension .ci)
31 \item Compile and Link with Charm's Fortran library
32 \item Run it !
33 \end{enumerate}
34
35 This is best explained with an example: the hello program.  It is a
36 simple ring program.  When executed, an array of several parallel
37 CHAREs is created.  Each chare "says" hello when it receives a
38 message, and then sends a message to the next chare. (Currently,
39 Fortran print is not working with Charm, so you'll have to imagine the
40 chares are saying hello. :) The Fortran main() subroutine starts off
41 the events.  And the SayHi() subroutine does the say-hello and
42 forward.
43
44 \section{Writing F90 Program}
45 To start, you need to create a Fortran Module to represent a chare,
46 e.g. <ChareName>Mod.
47
48 \begin{verbatim}
49
50       ## Just replace Hello throughout with your chare's name. ##
51       ## and add your chare's personal data below where indicated ##
52       ## Everything else remains the same ##
53       MODULE HelloMod
54
55       TYPE Hello
56       integer data
57       ## your chare's data goes here, the above integer is an example ##
58       END TYPE
59
60       TYPE HelloPtr
61       TYPE (Hello), POINTER ::  obj
62       integer*8 aid
63       END TYPE
64
65       END MODULE
66 \end{verbatim}
67
68 In the Fortran file you must write an allocate funtion for this chare
69 with the name: <ChareName>\_allocate
70
71 \begin{verbatim}
72       ## Just replace Hello throughout with your chare's name. ##
73       ## Everything else remains the same ##
74       SUBROUTINE Hello_allocate(objPtr, aid)
75       USE HelloMod
76       TYPE(HelloPtr) objPtr 
77       integer*8 aid
78
79       allocate(objPtr%obj)
80       objPtr%aid = aid;
81       END SUBROUTINE
82 \end{verbatim}
83
84 If you have written code for a chare array "Hello", as above, you will
85 have the following subroutine available to you:
86
87   \verb+<ChareName>\_CkNew(integer n, integer*8 aid)+
88      This function creates a chare array at runtime
89      where n is the number of items in the array, and
90            aid is the array ID which is returned to you.
91
92 We will see an example of using this function below.
93
94 \section{Writing Charm++ Interface File}
95
96 Now that you have the chare, you need to write one or more ENTRY
97 POINTs for it.  This is nothing but a Fortran subroutine that uses the
98 above module.
99 \begin{verbatim}
100       ## p1, p2, etc represent user parameters
101       ## the "objPtr, myIndex" stuff is required in every Entry Point.
102       ## CkExit() must be called by the chare to terminate.
103       SUBROUTINE SayHi(objPtr, myIndex, p1)
104       USE HelloMod
105       IMPLICIT NONE
106
107       TYPE(HelloPtr) objPtr
108       integer myIndex
109       integer p1
110
111       objPtr%obj%data = 20
112       if (myIndex < 4) then
113           call SendTo_Hello_SayHi(objPtr%aid, myIndex+1, 1);
114       else 
115           call CkExit()
116       endif
117 \end{verbatim}
118 Once you have written code for an Entry Point, you now have available
119 to you the following subroutine:
120 \begin{verbatim}
121    SendTo_<ChareName>_<SubroutineName>(integer*8 aid, integer myIndex,
122                           other parameters ....)
123      where aid is the target chare array ID
124            myIndex is the specific within the array
125                    we wish to send a message to
126            other parameters are the parameters in the above function.
127 \end{verbatim}
128
129 \section{Compile and Link}
130 You must have a Fortran main() subroutine where execution starts.
131 Typically this main function will create a chare array and send a
132 message to one of its members to get the computation started.
133 \begin{verbatim}
134       SUBROUTINE main()
135       USE HelloMod
136       integer i
137       integer*8 aid
138
139       print *, "hello"
140
141       call Hello_CkNew(5, aid)
142
143       call SendTo_Hello_SayHi(aid, 0, 1);
144
145       END
146 \end{verbatim}
147 \section{Writing Charm++ Interface File}
148 Now we move on to Step 2, the Charm Interface file.  This file must
149 have a different name from the Fortran file, and must have an
150 extension of .ci, e.g. if the above Fortran file is hellof.f90, this
151 file could be called hello.ci.  Basically, its purpose is to tell
152 Charm what you've done in the Fortran file, since Charm cannot read
153 Fortran as of now.
154 \begin{verbatim}
155       ## Just replace Hello throughout with your chare's name. ##
156       ## and add your chare's entry points below where indicated ##
157       ## Everything else remains the same ##
158       mainmodule hello {
159         extern module main;
160       
161         // Create some arbitrary message to hold your parameters
162         // The message must have a unique name for each Entry Point.
163         message HiMsg { int } ;
164       
165         array Hello {
166           entry Hello();
167
168           // Note how your Fortran function takes the above defined
169           // message instead of a list of parameters.
170           entry void SayHi(HiMsg *);
171
172           // Other entry points go here
173
174         };              
175       };
176 \end{verbatim}
177 If the function has more parameters: e.g. A Fortran function FF(int,
178 int, long) in module H, would be described in the .ci file as:
179 \begin{verbatim}
180   message MarshalParams { int, int, long };
181   array H {
182     entry H();
183     entry void FF(MarshalParams *);
184   }
185 \end{verbatim}
186 As mentioned above, the message must have a unique name.
187
188 \section{Compile and Link}
189 Lastly, you need to compile and link the Fortran program with the
190 Charm program as follows: (Let's say you have written hellof.f90, and
191 hello.ci)
192
193   First, you will need the lib/ directory and its contents in your
194   program directory.  So copy it there.  Then:
195
196   f90 -c hellof.f90
197     will create hellof.o
198
199   charmxi -f90 hello.ci
200     will create hello.decl.h, hello.def.h, and helloHelper.C
201     (helloHelper.C is not yet implemented, but in the interim
202      you can copy and edit the example.  Very simple.)
203
204   charmc -Ilib -c helloHelper.C
205     will create helloHelper.o
206
207   charmc -language charm++ -o hello hello.o hellof.o lib/libmain.a -lfsu  -lsunmath
208     will link hellof.o, helloHelper.o and Charm's Fortran library
209     to create your executable program 'hello'
210
211 \section{Run Program}
212
213 Finally, to run the program, make sure you have a nodelist file called
214 "nodelist" and containing, for example,
215
216 group main
217 host <computername>.cs.uiuc.edu <login>
218
219 and then type
220
221 ./conv-host +p2 hello
222
223 which will run 'hello' on two virtual processors.
224 \end{document}