Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / controlpoints.tex
1 \experimental{}
2 \charmpp{} currently includes an experimental automatic tuning
3 framework that can dynamically adapt a program at runtime to improve
4 its performance. The program provides a set of tunable knobs that are
5 adjusted automatically by the tuning framework. The user program also
6 provides information about the control points so that intelligent
7 tuning choices can be made. This information will be used to steer the
8 program instead of requiring the tuning framework to blindly search
9 the possible program configurations.
10
11 \textbf{Warning: this is still an experimental feature not meant for production applications}
12
13 \section{Exposing Control Points in a Charm++ Program}
14 The program should include a header file before any of its \texttt{*.decl.h} files:
15
16 \begin{alltt} 
17     #include <controlPoints.h> 
18 \end{alltt} 
19
20 The control point framework initializes itself, so no changes need to be made at startup in the program.
21
22 The program will request the values for each control point on PE 0. Control
23 point values are non-negative integers:
24
25 \begin{alltt} 
26     my_var = controlPoint("any_name", 5, 10);
27     my_var2 = controlPoint("another_name", 100,101);
28 \end{alltt} 
29
30 To specify information about the effects of each control point, make calls such as these once on PE 0 before accessing any control point values:
31
32 \begin{alltt} 
33     ControlPoint::EffectDecrease::Granularity("num_chare_rows");
34     ControlPoint::EffectDecrease::Granularity("num_chare_cols");
35     ControlPoint::EffectIncrease::NumMessages("num_chare_rows");
36     ControlPoint::EffectIncrease::NumMessages("num_chare_cols");
37     ControlPoint::EffectDecrease::MessageSizes("num_chare_rows");
38     ControlPoint::EffectDecrease::MessageSizes("num_chare_cols");
39     ControlPoint::EffectIncrease::Concurrency("num_chare_rows");
40     ControlPoint::EffectIncrease::Concurrency("num_chare_cols");
41     ControlPoint::EffectIncrease::NumComputeObjects("num_chare_rows");
42     ControlPoint::EffectIncrease::NumComputeObjects("num_chare_cols");
43 \end{alltt} 
44
45 For a complete list of these functions, see \texttt{cp\_effects.h} in \texttt{charm/include}.
46
47
48 The program, of course, has to adapt its behavior to use these new control point values. There are two ways for a the control point values to change over time. The program can request that a new phase (with its own control point values) be used whenever it wants, or the control point framework can automatically advance to a new phase periodically. The structure of the program will be slightly different in these to cases. Sections \ref{frameworkAdvancesPhases} and \ref{programAdvancesPhases} describe the additional changes to the program that should be made for each case.
49
50 \subsection{Control Point Framework Advances Phases}
51 \label{frameworkAdvancesPhases}
52
53 The program provides a callback to the control point framework in a manner such as this:
54
55 \begin{alltt} 
56     // Once early on in program, create a callback, and register it 
57     CkCallback cb(CkIndex_Main::granularityChange(NULL),thisProxy); 
58     registerCPChangeCallback(cb, true);
59 \end{alltt} 
60
61 In the callback or after the callback has executed, the program should request the new control point values on PE 0, and adapt its behavior appropriately.
62
63 Alternatively, the program can specify that it wants to call \texttt{gotoNextPhase();} itself when it is ready. Perhaps the program wishes to delay its adaptation for a while. To do this, it specifies \texttt{false} as the final parameter to \texttt{registerCPChangeCallback} as follows:
64
65 \begin{alltt} 
66    registerCPChangeCallback(cb, false);
67 \end{alltt} 
68
69
70 \subsection{Program Advances Phases}
71 \label{programAdvancesPhases}
72
73 \begin{alltt} 
74      registerControlPointTiming(duration); // called after each program iteration on PE 0
75      gotoNextPhase(); // called after some number of iterations on PE 0
76     // Then request new control point values
77 \end{alltt} 
78
79
80
81 \section{Linking With The Control Point Framework}
82
83 The control point tuning framework is now an integral part of the Charm++ runtime system. It does not need to be linked in to an application in any special way. It contains the framework code responsible for recording information about the running program as well as adjust the control point values. The trace module will enable measurements to be gathered including information about utilization, idle time, and memory usage. 
84
85 \section{Runtime Command Line Arguments}
86
87 Various following command line arguments will affect the behavior of the program when running with the control point framework. As this is an experimental framework, these are subject to change.
88
89 The scheme used for tuning can be selected at runtime by the use of one of the following options:
90 \begin{alltt} 
91      +CPSchemeRandom            Randomly Select Control Point Values
92  +CPExhaustiveSearch            Exhaustive Search of Control Point Values
93       +CPSimulAnneal            Simulated Annealing Search of Control Point Values
94  +CPCriticalPathPrio            Use Critical Path to adapt Control Point Values
95         +CPBestKnown            Use BestKnown Timing for Control Point Values
96          +CPSteering            Use Steering to adjust Control Point Values
97       +CPMemoryAware            Adjust control points to approach available memory
98 \end{alltt} 
99
100 To intelligently tune or steer an application's performance, performance measurements ought to be used. Some of the schemes above require that memory footprint statistics and utilization statistics be gathered. All measurements are performed by a tracing module that has some overheads, so is not enabled by default. To use any type of measurement based steering scheme, it is necessary to add a runtime command line argument to the user program to enable the tracing module:
101
102 \begin{alltt} 
103     +CPEnableMeasurements
104 \end{alltt}
105
106 The following flags enable the gathering of the different types of available measurements.
107 \begin{alltt} 
108         +CPGatherAll            Gather all types of measurements for each phase
109 +CPGatherMemoryUsage            Gather memory usage after each phase
110 +CPGatherUtilization            Gather utilization \& Idle time after each phase
111 \end{alltt} 
112
113
114 The control point framework will periodically adapt the control point values. The following command line flag determines the frequency at which the control point framework will attempt to adjust things.
115 \begin{alltt} 
116      +CPSamplePeriod     number The time between Control Point Framework samples (in seconds)
117 \end{alltt} 
118
119 The data from one run of the program can be saved and used in subsequent runs. The following command line arguments specify that a file named \texttt{controlPointData.txt} should be created or loaded. This file contains measurements for each phase as well as the control point values used in each phase. 
120 \begin{alltt} 
121          +CPSaveData            Save Control Point timings \& configurations at completion
122          +CPLoadData            Load Control Point timings \& configurations at startup
123      +CPDataFilename            Specify the data filename 
124 \end{alltt} 
125
126 It might be useful for example, to run once with \texttt{+CPSimulAnneal +CPSaveData} to try to find a good configuration for the program, and then use  \texttt{+CPBestKnown +CPLoadData} for all subsequent production runs.
127