Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / topology.tex
index b267cd8a1f18e82411085f037bfb362d87b8b9d7..df9af4488aac70bc053a2e5b3e164a5777e149e1 100644 (file)
@@ -1,37 +1,45 @@
-\section{Network Topology}
-\section{Node Topology}
-chao to write this section.
-
-The following calls provide information about the machines upon which the
-parallel program is executing.  Processing Element refers to a single CPU.
-Node refers to a single machine-- a set of processing elements which share
-memory (i.e. an address space).  Processing Elements and Nodes are numbered,
-starting from zero.
-
-Thus if a parallel program is executing on one 4-processor workstation and one
-2-processor workstation, there would be 6 processing elements (0, 1 ,2, 3, 4,
-and 5) but only 2 nodes (0 and 1).  A given node's processing elements are
-numbered sequentially.
+The following calls provide information about the machine upon which the
+parallel program is executed. A processing element (PE) refers to a single CPU,
+whereas a node refers to a single machine -- a set of processing elements that share
+memory (i.e. an address space).  PEs and nodes are numbered separately starting
+from zero, i.e., PEs are numbered in range $[0,CmiNumPes())$, and nodes are
+numbered in range $[0,CmiNumNodes())$.
 
-\function{int CkMyRank()} \index{CkMyRank}
-\desc{returns the rank number of the processor on which the call was made.
-Processing elements within a node are ranked starting from zero.}
-
-\function{int CkMyNode()} \index{CkMyNode}
-\desc{returns the address space number (node number) on which the call was made.}
+\section{Network Topology}
+Charm++ provides a unified abstraction for querying topology of IBM's BG/L, BG/P
+and BG/Q, and Cray's XT3, XT4, XT5 and XE6. Class TopoManager, which can be used 
+by including TopoManager.h, contains following member functions:
+
+\begin{description}
+\item [TopoManager():] Default constructor.
+\item [getDimNX(), getDimNY(), getDimNZ():] Returns the length of X, Y and Z
+dimensions (except BG/Q).
+\item [getDimNA(), getDimNB(), getDimNC(), getDimND(), getDimNE():] Returns the
+length of A, B, C, D and E dimensions on BG/Q.
+\item [getDimNT():] Returns the length of T dimension. TopoManager uses T
+dimension to represent different cores that reside within a physical code.
+\item [rankToCoordinates(int pe, int \&x, int \&y, int \&z, int \&t):] Get the
+coordinates of PE with number {\em pe} (except BG/Q).
+\item [rankToCoordinates(int pe, int \&a, int \&b, int \&c, int \&d, int \&e, int
+\&t):] Get the coordinates of PE with number {\em pe} on BG/Q.
+\item [coordinatesToRank(int x, int y, int z, int t):] Returns the number of PE
+with given coordinates (except BG/Q).
+\item [coordinatesToRank(int a, int b, int c, int d, int e, int t):] Returns the
+number of PE with given coordinates on BG/Q.
+\item [getHopsBetweenRanks(int pe1, int pe2):] Returns the distance between the
+given PEs in terms of the hops count on the network between the two PEs.
+\item [printAllocation(FILE *fp):] Outputs the allocation for a particular
+execution to the given file.
+
+\end{description}
 
-\function{int CkNumNodes()} \index{CkMyNodes}
-\desc{returns the total number of address spaces.}
 
-\function{int CkNodeFirst(int node)} \index{CkNodeFirst}
-\desc{returns the processor number of the first processor in this address space.}
+\section{Node Topology}
 
-\function{int CkNodeSize(int node)} \index{CkNodeSize}
-\desc{returns the number of processors in the address space on which the call was made.}
 
-\function{int CkNodeOf(int pe)} \index{CkNodeOf}
-\desc{returns the node number on which the call was made.}
+%Thus if a parallel program is executing on one 4-processor workstation and one
+%2-processor workstation, there would be 6 processing elements (0, 1 ,2, 3, 4,
+%and 5) but only 2 nodes (0 and 1).  A given node's processing elements are
+%numbered sequentially.
 
-\function{int CkRankOf(int pe)} \index{CkRankOf}
-\desc{returns the rank of the given processor within its node.}