Minor
[charm.git] / doc / charm++ / topology.tex
1 The following calls provide information about the machine upon which the
2 parallel program is executed. A processing element (PE) refers to a single CPU,
3 whereas a node refers to a single machine -- a set of processing elements that share
4 memory (i.e. an address space).  PEs and nodes are ranked separately starting
5 from zero, i.e., PEs are ranked in range 0 to {\em CmiNumPes()}, and nodes are
6 ranked in range 0 to {\em CmiNumNodes()}.
7
8 \section{Network Topology}
9 Charm++ provides a unified abstraction for querying topology of IBM's BG/L, BG/P
10 and BG/Q, and Cray's XT3, XT4, XT5 and XE6. Class TopoManager, which can be used 
11 by including TopoManager.h, contains following member functions:
12
13 \begin{description}
14 \item [TopoManager():] Default constructor.
15 \item [getDimNX(), getDimNY(), getDimNZ():] Returns the length of X, Y and Z
16 dimensions (except BG/Q).
17 \item [getDimNA(), getDimNB(), getDimNC(), getDimND(), getDimNE():] Returns the
18 length of A, B, C, D and E dimensions on BG/Q.
19 \item [getDimNT():] Returns the length of T dimension. TopoManager uses T
20 dimension to represent different cores that reside within a physical node.
21 \item [rankToCoordinates(int pe, int \&x, int \&y, int \&z, int \&t):] Get the
22 coordinates of PE with rank {\em pe} (except BG/Q).
23 \item [rankToCoordinates(int pe, int \&a, int \&b, int \&c, int \&d, int \&e, int
24 \&t):] Get the coordinates of PE with rank {\em pe} on BG/Q.
25 \item [coordinatesToRank(int x, int y, int z, int t):] Returns the rank of PE
26 with given coordinates (except BG/Q).
27 \item [coordinatesToRank(int a, int b, int c, int d, int e, int t):] Returns the
28 rank of PE with given coordinates on BG/Q.
29 \item [getHopsBetweenRanks(int pe1, int pe2):] Returns the distance between the
30 given PEs in terms of the hops count on the network between the two PEs.
31 \item [printAllocation(FILE *fp):] Outputs the allocation for a particular
32 execution to the given file.
33 \end{description}
34
35 \noindent For example, one can obtain rank of a processor, whose coordinates are known, on 
36 BG/P as well as on Cray XE6 using the following code:
37
38 \begin{alltt}
39 TopoManager tmgr;
40 int rank,x,y,z,t;
41 x = y = z = t = 2;
42 rank = tmgr.coordinatesToRank(x,y,z,t);
43 \end{alltt}
44
45 \noindent For more examples, please refer to examples/charm++/topology.
46 %\section{Node Topology}
47
48 %Thus if a parallel program is executing on one 4-processor workstation and one
49 %2-processor workstation, there would be 6 processing elements (0, 1 ,2, 3, 4,
50 %and 5) but only 2 nodes (0 and 1).  A given node's processing elements are
51 %numbered sequentially.
52
53