Added description of makemblock.
authorOrion Lawlor <olawlor@acm.org>
Fri, 18 Apr 2003 17:12:20 +0000 (17:12 +0000)
committerOrion Lawlor <olawlor@acm.org>
Fri, 18 Apr 2003 17:12:20 +0000 (17:12 +0000)
doc/mblock/manual.tex

index 66222769413322b72f805d6ccaf5e5e7e438c426..cad2a991df235810deeb91c701313e569a2a6c93 100644 (file)
@@ -176,6 +176,31 @@ To compile a MULTIBLOCK program, pass the {\tt -language mblock} (for C) or
 In a charm installation, see charm/version/pgms/charm++/mblock/
 for example and test programs.
 
+\section{Preparing Input Files}
+The Multiblock framework reads its description of the problem
+domain from input "block" files, which are in a Multiblock-specific format.
+The files are named with the pattern \kw{prefix}\kw{number}.\kw{ext}, where
+\kw{prefix} is a arbitrary string prefix you choose; \kw{number} is the 
+number of this block (virtual processor); and \kw{ext} is either ``mblk'',
+which contains binary data with the block coordinates, or ``bblk'', 
+which contains ASCII data with the block's boundary conditions.
+
+You generate these Multiblock input files using a tool called \kw{makemblock},
+which can be found in charm/version/pgms/charm++/makemblock.
+\kw{makemblock} can read a description of the problem domain 
+generated by the structured meshing program Gridgen (from Pointwise)
+in .grd and .inp format; or read a binary .msh format.
+\kw{makemblock} divides this input domain into the number of blocks
+you specify, then writes out .mblk and .bblk files.
+
+For example, to divide the single binary mesh ``in1.msh'' into
+20 pieces ``out00001.[mb]blk''..``out00020.[mb]blk'', you'd use
+\begin{verbatim}
+       makemblock in1.msh 20 out
+\end{verbatim}
+
+You would then run this mesh using 20 virtual processors.
+
 
 \section{Multiblock Framework API Reference}
 
@@ -197,8 +222,8 @@ file or computed from command-line parameters.
   \args{character*, intent(in)::prefix}
   \args{integer, intent(out)::err}
 This function is called to set the block filename prefix. 
-For example, if the input block files are named ``gridX000001.mblk''
-and ``gridX000002.mblk'', the prefix is the string ``gridX''.
+For example, if the input block files are named ``gridX00001.mblk''
+and ``gridX00002.mblk'', the prefix is the string ``gridX''.
 
 \vspace{0.2in}
 \function{int MBLK\_Set\_nblocks(const int n);}
@@ -212,6 +237,9 @@ parallelism; so be sure to have at least as many blocks as processors.
 We recommend using several times more blocks than processors, to ease 
 load balancing and allow adaptive overlap of computation and communication.
 
+Be sure to set the number of blocks equal to the number of virtual 
+processors (+vp command-line option).
+
 \vspace{0.2in}
 \function{int MBLK\_Set\_dim(const int n);}
 \function{subroutine MBLK\_Set\_dim(n, err)}