use cmireduce during recovery
[charm.git] / doc / parfum / program.tex
1 \subsection{Getting ParFUM}\label{sec:getting_parfum}
2
3 ParFUM is built on \charmpp\, so you must begin by
4 downloading the latest source version of \charmpp\ from
5 {\tt http://charm.cs.uiuc.edu/}.  Build the source by running  
6 {\tt ./build} and answering the interactive prompts, or by manually specifying the configuration you want to the build script. Make sure to build the \charmpp\ libraries, not just the core system.
7
8 In a charm installation, see charm/examples/ParFUM/ for example and test programs.
9
10
11 \subsection{Structure of a Typical ParFUM Program}
12
13 A typical ParFUM program consists of two functions: {\tt init()} and {\tt driver}. The {\tt init()} function runs only on the first processor, and typically does specialized I/O and startup tasks. In most ParFUM programs {\tt init()} is primarily used to read in a serial mesh. Once {\tt init()} completes, ParFUM partitions the mesh and distributes it among all processors. Then {\tt driver()} is called for every chunk on every processor and performs the main work of the program. This program structure is shown in Figure~\ref{fig:parfum_structure}. In the language of the TCHARM manual, {\tt init()} runs in the serial context and {\tt driver()} runs in the parallel context.
14
15 \begin{figure}[h]
16 \begin{center}
17 \includegraphics[height=3in]{fig/parfum_structure}
18 \end{center}
19 \caption{A typical ParFUM program consists of an {\tt init()} function running in serial context and a {\tt driver()} function running in parallel context.}
20 \label{fig:parfum_structure}
21 \end{figure}
22
23 In pseudocode, a simple ParFUM program would have the following structure:
24
25 \begin{alltt}
26      subroutine init
27           read the serial mesh and configuration data
28      end subroutine
29 /* after init, the FEM framework partitions the mesh */
30      subroutine driver
31           get local mesh chunk
32           time loop
33                FEM computations
34                communicate boundary conditions
35                more FEM computations
36           end time loop
37      end subroutine
38 \end{alltt}
39
40 \subsection{ParFUM Programs without init/driver}
41
42 Although ParFUM provides the init/driver structure as a convenience to the programmer, you can write a ParFUM program without using init or driver. This is a more flexible approach, but it is more complicated than an init/driver program.
43
44 In pseudocode, a ParFUM program with a stand-alone main function might look like this:
45
46 \begin{alltt}
47    main program
48       MPI_Init
49       FEM_Init(MPI_COMM_WORLD)
50       if (I am master processor)
51          read mesh
52       partition mesh
53       time loop
54           FEM computations
55           communicate boundary conditions
56           more FEM computations
57       end time loop
58    end main program
59 \end{alltt}
60
61
62 In this mode, the FEM framework does not set a default reading or writing mesh, and does no partitioning; you must use the FEM\_Mesh routines to create and 
63 partition your mesh. See the AMPI manual for details on how to declare
64 the main routine, or the file main.C in ParFUM for an example of how to write a stand-alone main routine. Compiling a ParFUM program without init or driver requires slightly different link flags than a typical ParFUM program, see the compilation section for details.
65
66
67 \subsection{Compilation}
68
69 To compile and link a ParFUM program, you must first have a working copy of \charmpp\ and the ParFUM libraries. The process for downloading and building this software is described in section \ref{sec:getting_parfum}.
70
71 To compile a FEM program, compile and link using {\tt charmc}, and pass the flag {\tt -language ParFUM} to charmc when linking. If your program uses its own {\tt main} function rather than init and driver, pass {\tt -language AMPI} instead.
72
73 \subsection{Execution}
74
75 At runtime, a Charm++/FEM framework program accepts the following
76 options, in addition to all the usual Charm++ options described in 
77 the Charm++ ``Installation and Usage Manual''.
78
79 \begin{itemize}
80
81 \item {\tt +vp} $v$  
82
83 Create $v$ mesh chunks, or ``virtual processors''.
84 By default, the number of mesh chunks is equal to the number of 
85 physical processors (set with {\tt +p} $p$).
86
87
88 \item {\tt -write}
89
90 Skip \kw{driver()}.
91 After running \kw{init()} normally, the framework partitions the mesh, 
92 writes the mesh partitions to files, and exits.  As usual, the
93 {\tt +vp} $v$ option controls the number of mesh partitions.
94
95 This option is only used in programs with an {\tt init} function.
96
97 \item {\tt -read}
98
99 Skip \kw{init()}.
100 The framework reads the partitioned input mesh from files
101 and calls \kw{driver()}.  Together with {\tt -write}, this option
102 allows you to separate out the mesh preparation and partitioning 
103 phase from the actual parallel solution run.
104
105 This can be useful, for example, if \kw{init()} requires more memory 
106 to hold the unpartitioned mesh than is available on one processor of 
107 the parallel machine.  To avoid this limitation, you can run the program
108 with {\tt -write} on a machine with a lot of memory to prepare the input
109 files, then copy the files and run with {\tt -read} on a machine with 
110 a lot of processors.
111
112 {\tt -read} can also be useful during debugging or performance tuning, 
113 by skipping the (potentially slow) mesh preparation phase.
114 This option is only used in programs with a {\tt driver} function.
115
116 \item {\tt +tcharm\_trace fem}
117
118 Give a diagnostic printout on every call into the ParFUM framework.
119 This can be useful for locating a sudden crash, or understanding
120 how the program and framework interact.  Because printing the 
121 diagnostics can slow a program down, use this option with care.
122
123 \end{itemize}