Made converse manual use pplmanual style.
[charm.git] / doc / converse / simulator.tex
1 Running with the simulator:
2
3
4 \converse{} provides a simple parallel machine simulator for developing
5 and debugging purposes. It simulates a message passing system. The simulated
6 machine is a collection of processing nodes connected with a communication
7 network. Each node is composed of an application processor, local memory, and 
8 a communication coprocessor. 
9 The simulator is a beta version, particularly using the simulator timers
10 for performance measurements has not been tested yet.
11
12 In order to run \converse{} programs with the simulator:
13 \begin{item}
14 \item link user program with <machine>/lib/libck-unimain.o
15 \item prepare a configuration file as described below
16 \item to run, type pgm +pN (and possibly other runtime options) where
17    N is the number of processors.
18 \end{itemize}
19
20
21
22 The basic task of the simulator is to manage the message passing
23 obeying various machine and network parameters.
24 A message experiences delays in various components of the machine. These
25 include: 1) sender application processor, 2) sender communication coprocesssor, 
26 3) network, 4) receiver communication processor, and 5) receiver
27 application processor.
28 Each component of the delayed is modelled by the widely used formula
29 $\alpha + n\beta$ where $\alpha$ is the startup cost, and $\beta$ is the
30 cost per byte. 
31 In addition to message delay parameters, there are others related to the 
32 network capacity and random variations in network delays. These parameters
33 are specified in a configuration file named "sim.param" in the directory
34 of the user program. If the simulator can't find this file, it assumes
35 default values (mostly zero latencies).
36 Figure~\ref{fig:simconfig} lists a sample configuration. The lines
37 starting with the \# sign are treated as comments. Each line contains
38 a keyword followed by some numbers. The explanation of each keyword
39 is given below:
40
41 \begin{description}
42 \item[\verb+cpu_recv_cost+] $\alpha$ and  $\beta$ values  for the software
43                             cost of a message-receive at the application
44                             processor.
45 \item[\verb+cpu_send_cost+] $\alpha$ and  $\beta$ values  for the software
46                             cost of a message-send at the application
47                             processor.
48 \item[\verb+rcp_cost+] $\alpha$ and  $\beta$ values for a message-receive 
49                        at the communication processor.
50 \item[\verb+scp_cost+] $\alpha$ and  $\beta$ values for a message-send
51                        at the communication processor.
52 \item[\verb+net_cost+] $\alpha$ and  $\beta$ values for a message-send
53                        in the netowrk.
54 \item[\verb+cpu_queue_threshold_number+] max number of messages queued
55                        at the application processors's incoming message queue.
56 \item[\verb+cpu_queue_threshold_size+] max cumulative size of messages in bytes
57                        queued at the application processors's incoming message 
58                        queue.
59
60
61 \item[\verb+cpu_queue_threshold_number+] max number of messages in the incoming
62                        message queue of communication processor.   
63
64
65 \item[\verb+rcp_queue_threshold_number+] max number of messages in the 
66                        incoming-message-queue of communication processors.                    
67 \item[\verb+rcp_queue_threshold_size+] max cumulative size of messages in bytes
68                        in the incoming-message-queue of communication 
69                        processors.
70
71 \item[\verb+net_queue_threshold_number+] max number of transient messages in 
72                        the network.
73
74 \item[\verb+net_queue_threshold_size+] max cumulative size of transient 
75                        messages in bytes in the network.
76
77 \item[\verb+latency-fixed] no random variations in the network latency 
78                            ($\alpha$)
79
80 \item[\verb+latency-rand+] network latency ($\alpha$) is incremented by
81                        a random value distributed exponentially. The first
82                        number after the keyword is the mean of the
83                        exponential distribution. The second number is the
84                        initial seed vbalue for the random number generator.
85
86
87 \item[\verb+processor_scale+] The simulator scales the measured time
88                       execution of code-blocks by this value.
89
90 \item[\verb+periodic_interval+] \converse{} has periodic checks for
91                       various purposes. This is the time on seconds
92                       those checks are called.
93 \end{description}
94
95
96 \begin{figure}
97 \begin{alltt}
98 #latency parameters
99 cpu_recv_cost 1E-6 1E-7              
100 cpu_send_cost 1E-6 1E-7
101 rcp_cost      1E-3 1E-7
102 scp_cost      1E-6 1E-7
103 net_cost      1E-6 1E-7
104
105
106 #capacity parameters
107 # choose one 
108 cpu_nolimit
109 #cpu_queue_threshold_number 100000
110 #cpu_queue_threshold_size   100000
111
112
113 #choose one
114 scp_nolimit
115 #scp_queue_threshold_number 100000
116 #scp_queue_threshold_size   100000
117
118 #choose one
119 rcp_net_nolimit
120 #rcp_queue_threshold_number 100000
121 #rcp_queue_threshold_size   100000
122 #net_queue_threshold_number 100000
123 #net_queue_threshold_size   100000
124
125 #random variations in latency
126 #choose one
127 latency-fixed
128 #latency-rand   0.0001 123456
129
130 processor_scale 1.0
131 periodic_interval 0.1
132 \end{alltt}
133 \caption{A sample configuration file for the simulator}
134 \label{fig:simconfig}
135 \end{figure}