Docs: Review f90charm 11/4911/2
authorEvan Ramos <evan@hpccharm.com>
Mon, 21 Jan 2019 23:15:57 +0000 (17:15 -0600)
committerEvan Ramos <evan@hpccharm.com>
Tue, 22 Jan 2019 18:57:25 +0000 (12:57 -0600)
Change-Id: I04f4ae1dd0dab6160ac430e93bbf5e7fb90c1df5

doc/f90charm/manual.rst

index c40e6ec..0caa70c 100644 (file)
@@ -55,15 +55,15 @@ example:
 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.
+F90Charm runtime library. The [aid] is the handle of the array returned
+by the F90Charm library, and the user shouldn’t change it.
 
-Same as in Charm++ programs, you need to write a .ci interface file so
+In F90Charm as in Charm++, 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,
+in Charm++. Second, F90Charm currently only supports up to 3D Chare
+arrays, and you cannot define Chare, Group, and NodeGroup 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
@@ -89,50 +89,50 @@ corresponding Fortran90 subroutine for it:
 
 ``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
+Note that the first argument is the Chare pointer as declared
+previously, and 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.
+declared in the .ci file. 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:
+On the caller side, the decl/def files generated by Charm++’s translator
+also provide the following functions for Chare creation and remote method
+invocation. For each Chare declared in .ci files, these subroutines are
+generated for use in Fortran90 code:
 
 ``<ChareName>_CkNew(integer n, integer*8 aid)``
 
-This subroutine creates the chare array of size n. For higher
+This subroutine creates a chare array of size ``n``. For higher
 dimensional array creation, specify one integer for each dimension. For
 example, to create a 3D array:
 
 ``<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:
+For each entry method, a corresponding ``Invoke`` method is provided (1D
+example shown here):
 
 ``<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
+This subroutine will send a message to the array element with index
+``myIndex``. Similarly, for arrays with higher dimensions, replace ``myIndex``
+by corresponding number of array indices. Broadcasts are supported as
 well:
 
 ``<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:
+First, as 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:
+include these C++ files in Fortran90 code. Thus, currently, it is the user’s
+task to write a short C++ file including these two headers files. You
+should also provide definitions for readonly variables in this C++ file.
+It can be as simple as this:
 
 ::
 
    #include "hello.decl.h"
-   int chunkSize;  // readonly variables define here
+   int chunkSize;  // define readonly variables here
    #include "hello.def.h"
 
 In the future, this file could be generated automatically by the
@@ -153,7 +153,7 @@ Take the readonly variable chunkSize as an example:
 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
+Third, for the user’s convenience, several Charm++ runtime library functions
 have their Fortran interface defined in the F90Charm library. These
 currently include:
 
@@ -167,27 +167,26 @@ currently include:
 Here is a summary of current constraints to write F90 binding Charm++
 programs:
 
-#. in .ci files, only 1-3D Chare array is supported.
+#. Only one- to three-dimensional chare arrays are supported.
 
-#. readonly variables must be basic types, ie. they have to be integer,
-   float, etc scalar types or array types of these basic scalar types.
+#. readonly variables must be basic types, i.e. they have to be integers,
+   floats, etc. scalar types or array types of these basic scalar types.
 
-#. instead of program main, your f90 main program starts from subroutine
-   f90charmmain.
+#. Instead of ``program main``, your f90 main program starts from
+   ``subroutine f90charmmain``.
 
-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.
+These details are best illustrated with an example: a hello world program.
+When executed, an array of several parallel chares is created, forming a ring.
+Each chare prints a string when it receives a message, and then sends a
+message to the next chare in the ring. The Fortran ``f90charmmain`` subroutine
+begins execution, and the ``SayHi`` subroutine performs each chare's task.
 
-Writing Charm++ Interface File
-==============================
+Writing the 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++.
+In this step, you need to write a Charm++ interface file (.ci).
+In the file you can declare parallel chare arrays and their
+entry methods. The syntax is the same as in Charm++.
 
 ::
 
@@ -216,8 +215,8 @@ also are not supposed to declare messages. Furthermore, the entry
 functions must be declared with explicit parameters instead of using
 messages.
 
-Writing F90 Program
-===================
+Writing the F90 Program
+=======================
 
 To start, you need to create a Fortran Module to represent a chare, e.g.
 {ChareName}Mod.
@@ -261,7 +260,7 @@ with the name: Hello_allocate.
          END SUBROUTINE
 
 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.
+start to write entry functions as declared in the .ci files.
 
 .. code-block:: fortran
 
@@ -326,42 +325,42 @@ 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.
 
-Compile and Link
-================
+Compilation and Linking
+=======================
 
 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)
+runtime system as follows: (Let’s say you have written ``hellof.f90``, ``hello.ci`` and
+``hello.C``.)
 
 .. code-block:: bash
 
      > charmc hello.ci -language f90charm
 
-will create hello.decl.h, hello.def.h
+will create ``hello.decl.h`` and ``hello.def.h``.
 
 .. code-block:: bash
 
      > charmc -c hello.C
 
-will compile the hello.C with hello.decl.h, hello.def.h.
+will compile ``hello.C`` with ``hello.decl.h`` and ``hello.def.h``.
 
 .. code-block:: bash
 
      > charmc -c hellof.f90
 
-charmc will invoke fotran compiler;
+charmc will invoke the Fortran compiler:
 
 .. code-block:: bash
 
      > charmc -o hello hello.o hellof.o -language f90charm
 
-will link hellof.o, hello.o against Charm’s Fortran90 library to create
-your executable program ’hello’.
+will link ``hellof.o`` and ``hello.o`` against Charm’s Fortran90 library to create
+a new executable program, ``hello``.
 
-There is a 2D array example at charm/examples/charm++/f90charm/hello2D.
+A 2D array example can be found in ``charm/examples/charm++/f90charm/hello2D``.
 
-Run Program
-===========
+Running the Program
+===================
 
 To run the program, type:
 
@@ -369,4 +368,4 @@ To run the program, type:
 
     > ./charmrun +p2 hello
 
-which will run ’hello’ on two virtual processors.
+which will run ``hello`` on two PEs.