Update references to hapi_src to hapi_impl and revert hapiRegisterCallbacks

[charm.git] / doc / f90charm / manual.tex

\documentclass[11pt]{article}

\pagestyle{headings}

\title{Fortran90 Bindings for Charm++}

\begin{document}

\maketitle

Charm++ is a parallel object language based on C++. The f90charm module is to
provide Fortran90 programs a f90 interface to Charm++. Using the F90Charm interface,
users can write Fortran90 programs in a fashion similar to Charm++, which allows
creation of parallel object arrays (Chare Arrays) and sending messages between 
them.

To interface Fortran90 to Charm++ and thus obtain a parallel version of your 
program you need to do the following things:
\begin{enumerate}
\item Write a Charm Interface file (extension .ci)
\item Write your F90 program with f90charmmain() as main program;
\item Write implementations of Chare entry methods in the F90 program;
\item Compile and Link with Charm's Fortran library
\item Run it!
\end{enumerate}

\section{Overview}

Here we suppose you already know most concepts in Charm++ and have done some 
Charm++ programming. \\
Unlike in C++, we don't have classes in Fortran90. Thus, a Chare in F90Charm is 
represented as a Fortran type structure. Here is an example:

\begin{verbatim}

      ## Just replace Hello throughout with your chare's name. ##
      ## and add your chare's personal data below where indicated ##
      ## Everything else remains the same ##
      MODULE HelloMod

      TYPE Hello
      ## your chare's data goes here, the integer below is an example ##
      integer data
      END TYPE

      TYPE HelloPtr
      TYPE (Hello), POINTER :: obj
      integer*8 aid
      END TYPE

      END MODULE
\end{verbatim}
You can think of this module as a Chare declaration. Type [Hello] defines 
arbitrary user program data and HelloPtr defines the Chare pointer which the
Fortran program will use later to communicate with the F90Charm runtime 
library, the [aid] is the handle of the array returned by the F90Charm library, user 
shouldn't change it.

Same as in Charm++ programs, you need to write a .ci interface file
so that the Charm translator will generate helper functions. The syntax of .ci files
is the same as in Charm++, however, for F90Charm, there are certain
constraints. First, you don't need to declare the main chare as like in Charm++;
Second, F90Charm currently only supports up to 3D Chare arrays, and you cannot define 
Chare, Group, and Node Group types. Third, there are no message declarations in .ci files, 
all the entry functions must be declared in the parameter marshalling 
fashion of Charm++.
Essentially, users can declare in .ci files readonly variables and 1-3D
chare arrays with parameter marshalled entry methods.

It is the programmer's responsibility to write the implementation of Chare
entry methods. The decl and def files generated by Charm++'s translator define
the interface functions programmer need to write.

For each Chare defined in the .ci file, the user must write these functions
for F90Charm's runtime:

  \verb+SUBROUTINE <ChareName>_allocate(objPtr, aid, index)+

  You can think of this function as a constructor for each array element 
with array index [index]. For a 3D array, for example, you can replace index in the 
example by a 3D array index [index1, index2, index3]. 
In this function the user must allocate memory for 
the Chare's user data and perform any initialization.

  For each Chare entry method you have declared, you should write the corresponding 
Fortran90 subroutine for it:

  \verb+SUBROUTINE <ChareName>_Entry_<EntryName>(charePtr, myIndex, data1, data2 ... )+

  Note, the first argument is the Chare pointer as you declared previously, the second argument is the array index which will be passed from the Charm runtime. 
The rest of the parameters should be the same as you declare the entry methods
in .ci files. For higher dimensional arrays, replace myIndex by "myIndex1, myIndex2" for example.

On the other side, the decl/def files generated by Charm++'s translator also
provide these functions for Chare creation and remote method invocation. 
for each Chare declared in .ci files, these subroutines are generated for use
 in the Fortran90 program:

  \verb+<ChareName>_CkNew(integer n, integer*8 aid)+

  This subroutine creates the chare array of size n. For higher dimensional
array creation, specify one integer for each dimension. For example, to create
a 3D array:

  \verb+<ChareName>_CkNew(integer dim1, integer dim2, integer dim3, integer*8 aid)+

And for each entry method, this function is available for use in F90 program
if it is 1D array:

  \verb+<ChareName>_Invoke_<EntryName>(charePtr, myIndex, data1, data2 ... )+

  This subroutine will send a message to the array element with the index
as myIndex. Similarly for arrays with higher dimensions, replace myIndex by
corresponding number of array indices. Broadcasts are supported as well:

  \verb+<ChareName>_Broadcast_<EntryName>(charePtr, data1, data2 ... )+

There are several others things you need to know.

First, as same in Charm++, each .ci file will generate two header files:
.decl.h and .def.h. However, in Fortran90 charm, you are not able to include 
these C++ files in Fortran90 code. Thus, currently, it is user's 
task to write a simple C++ code to include these two headers files. 
You should also declare readonly variables as in C++ in this file. This is as 
simple as this:

\begin{verbatim}
#include "hello.decl.h"
int chunkSize;  // readonly variables define here
#include "hello.def.h"
\end{verbatim}

In the future, this file could be generated automatically by the translator.

Second, you can still use readonly variables as in Charm++. However, since
there are no global variables as in C++ in Fortran90, you have to access them
explicitly via function call. Here are the two helper functions that the 
translator generates:

Take the readonly variable chunkSize as an example:
\begin{verbatim}
Set_Chunksize(chunkSize);
Get_Chunksize(chunkSize);
\end{verbatim}
These two functions can be used in user's Fortran program to set and get 
readonly variables.

Third, for user's convenience, several Charm++ runtime library functions
have their Fortran interface defined in the F90Charm library. These currently
include:
\begin{verbatim}
CkExit()
CkMyPe(integer mype)
CkNumPes(integer pes)
CkPrintf(...)    // note, the format string must terminated with '$$'
\end{verbatim}

Here is a summary of current constraints to write F90 binding Charm++ programs:
\begin{enumerate}
\item in .ci files, only 1-3D Chare array is supported.
\item readonly variables must be basic types, ie. they have to be integer, 
float, etc scalar types or array types of these basic scalar types.
\item instead of program main, your f90 main program starts from subroutine 
f90charmmain.
\end{enumerate}

All these are best explained with an example: the hello program.  It is a
simple ring program.  When executed, an array of several parallel
Chares is created.  Each chare "says" hello when it receives a
message, and then sends a message to the next chare. The Fortran f90charmmain() 
subroutine starts off the events.  And the SayHi() subroutine does the 
say-hello and call next chare to forward.

\section{Writing Charm++ Interface File}
In this step, you need to write a Charm++ interface file with extension of
.ci. In this file you can declare parallel Chare Arrays and their entry 
functions. The syntax is same as in Charm++.
\begin{verbatim}
      ## Just replace Hello throughout with your chare's name. ##
      ## and add your chare's entry points below where indicated ##
      ## Everything else remains the same ##
      mainmodule hello {
        // declare readonly variables which once set is available to all
        // Chares across processors.      
        readonly int chunkSize;

        array [1D] Hello {
          entry Hello();

          // Note how your Fortran function takes the above defined
          // message instead of a list of parameters.
          entry void SayHi(int a, double b, int n, int arr[n]);

          // Other entry points go here
          entry [reductiontarget] void MyReduction(int result);
        };              
      };
\end{verbatim}
Note, you cannot declare a main chare in the interface file, and you also are not 
supposed to declare messages. Furthermore, the entry functions must be 
declared with explicit parameters instead of using messages. 

\section{Writing F90 Program}
To start, you need to create a Fortran Module to represent a chare,
e.g. \{ChareName\}Mod.

\begin{verbatim}

      ## Just replace Hello throughout with your chare's name. ##
      ## and add your chare's personal data below where indicated ##
      ## Everything else remains the same ##
      MODULE HelloMod

      TYPE Hello
      ## your chare's data goes here ##
      integer data
      END TYPE

      TYPE HelloPtr
      TYPE (Hello), POINTER ::  obj
      integer*8 aid
      END TYPE

      END MODULE
\end{verbatim}

In the Fortran file you must write an allocate function for this chare
with the name: Hello\_allocate.

\begin{verbatim}
      ## Just replace Hello throughout with your chare's name. ##
      ## Everything else remains the same ##
      SUBROUTINE Hello_allocate(objPtr, aid, index)
      USE HelloMod
      TYPE(HelloPtr) objPtr 
      integer*8 aid
      integer index

      allocate(objPtr%obj)
      objPtr%aid = aid;
      ## you can initialize the Chare user data here
      objPtr%obj%data = index
      END SUBROUTINE
\end{verbatim}

Now that you have the chare and the chare constructor function, you can start
 to write one or more entry functions as declared in .ci files.
\begin{verbatim}
      ## p1, p2, etc represent user parameters
      ## the "objPtr, myIndex" stuff is required in every Entry Point.
      ## CkExit() must be called by the chare to terminate.
      SUBROUTINE Hello_Entry_SayHi(objPtr, myIndex, data, data2, len, s)
      USE HelloMod
      IMPLICIT NONE

      TYPE(HelloPtr) objPtr
      integer myIndex
      integer data
      double precision data2
      integer len
      integer s(len)

      objPtr%obj%data = 20
      if (myIndex < 4) then
          call Hello_Invoke_SayHi(objPtr%aid, myIndex+1, 1, data2, len, s);
      else 
          call CkExit()
      endif
\end{verbatim}

Preliminary support for reductions is available as well. Support is limited to
reducing from a chare array to the first member of the same array. Only basic
built-in reducers are available. For an entry method named MyReduction, tagged
as a reduction target in the interface file, a contribution can be made as
follows:

\begin{verbatim}
      external Hello_ReductionTarget_MyReduction

      call Hello_contribute(objPtr%aid, myIndex, sizeof(myIndex), myValue, CHARM_SUM_INT, Hello_ReductionTarget_MyReduction)
\end{verbatim}

Now, you can write the main program to create the chare array and start the 
program by sending the first message.
\begin{verbatim}
      SUBROUTINE f90charmmain()
      USE HelloMod
      integer i
      double precision d
      integer*8 aid
      integer  s(8)

      call Hello_CkNew(5, aid)

      call set_ChunkSize(10);

      do i=1,8
          s(i) = i;
      enddo
      d = 2.50
      call Hello_Invoke_SayHi(aid, 0, 1, d, 4, s(3:6));

      END
\end{verbatim}
This main program creates an chare array Hello of size 5 and send a message with
an integer, an double and array of integers to the array element of index 0.

\section{Compile and Link}
Lastly, you need to compile and link the Fortran program with the
Charm program as follows: (Let's say you have written hellof.f90, 
hello.ci and hello.C)
\begin{verbatim}
  charmc hello.ci -language f90charm
\end{verbatim}
    will create hello.decl.h, hello.def.h

\begin{verbatim}
  charmc -c hello.C
\end{verbatim}
    will compile the hello.C with hello.decl.h, hello.def.h.

\begin{verbatim}
  charmc -c hellof.f90
\end{verbatim}
    charmc will invoke fotran compiler;

\begin{verbatim}
  charmc -o hello hello.o hellof.o -language f90charm
\end{verbatim}
    will link hellof.o, hello.o against Charm's Fortran90 library
    to create your executable program 'hello'.

  There is a 2D array example at charm/examples/charm++/f90charm/hello2D.

\section{Run Program}

To run the program, type:

./charmrun +p2 hello

which will run 'hello' on two virtual processors.

\end{document}