PMDBtool

The PMDBtool program provides simple access to many of the functionalities of the Parallel Mesh Database without writing a whole program for each little task.

PMDBtool takes one command-line argument, the name of a command script file. It parses the command file and does things like loading and paritioning meshes, load balancing, and computing our metric statistics.

PMDBtool commands

These commands can be placed in a script file which is given on the command line. Text on a line after a # character is treated as a comment.

- trace
- trace <bool_val>
Turn on or off trace output, depending on the boolean argument. A missing argument is taken to mean turn on tracing. 
- compress <level>
Set the output compression level. Valid compression levels are The default compression is gzip. 
- indir "path"
- outdir "path"
Sets default input and output directories to the given string. The path string must be quoted. Any input or output files which are given on subsequent lines and which do not have a directory included in their filename will have this path prepended to them before opening. These can be issued multiple times in an execution of the program to change directories on the fly. 
- model "file"
Loads the model file in "file.smd". This should be done first, just as it usually is done in a Mesh Database/PMDB application. This command will call GM_createFromFile() to load the model file. 
- part <type> "file"
Load "file.sms" file and partition onto all the processors. <type> can be inertial or orthogonal. This command will call pmdb_inertia_rb() or pmdb_ortho_rb(). 
- read_sms "file"
Load saved PMDB files in "file.procid.sms" and "file.procid.pmdb". This command will call pmdb_read_msh_par(). 
- read_split_sms "file"
Load split mesh files in "file.procid.sms". This command will call pmdb_load_split_sms(). The interprocessor links normally stored in the .pmdb files are generated by PMDB. 
- write_sms "file"
Write PMDB files "file.procid.sms" and "file.procid.pmdb". This command will call pmdb_write_msh_par(). 
- metrics "prefix" "infix"
Print metric information about the current mesh and partition. This results in a call to pmdb_metrics(); with the args here passed as the prefix and infix strings. 
- loads max/avg/local/global
Print values of load (possibly weighted) and the number of regions in the current mesh and partition. Any combination of max, avg, local, and global can be displayed, with multiple values separated by spaces. max prints the maximum values on any processors, avg the average values, local the local values from each processor, and global the overall totals. 
- si max/avg/local/global
Compute and print values of surface index metrics in the current mesh and partition. Any combination of max, avg, local, and global can be displayed, with multiple values separated by spaces. max prints the maximum value on any processor (MLSI), avg the average value, local the local value from each processor, and global the overall total (GSI). 
- disconn max/avg/local ent_type
Compute and print the number of disjoint connected components in the current mesh and partition. Any combination of max, avg, and local can be displayed, with multiple values separated by spaces. max prints the maximum number of components on any processor, avg the average count, and local the local count from each processor. ent_type is the type of entity adjacency used for the calculation, which could be face, edge, or vertex. 
- adjacency max/avg/local
Compute and print the number and percentage of partition adjacencies current mesh and partition. Any combination of max, avg, and local can be displayed, with multiple values separated by spaces. max prints the maximum number of processors adjacent to any processor, avg the average count, and local the local adjacency count from each processor. 
- duplicates ent_type
Print the number of duplicated partition boundary entities in the current mesh and partition. ent_type is the type of entity, which could be face, edge, or vertex. 
- comm_matrix
Compute and print the communication matrix for the current mesh and partition. 
- int_matrix
Compute and print the interface matrix for the current mesh and partition. 
- centroids "file"
Write the centroids of all mesh regions on each processor i in a file file.i.cent. 
- dx <dx_opts> "file"
Write Data Explorer files which represent the currently loaded mesh. <dx_opts> can include the tokens color, bw, surface, 3d, or 2d. The defaults are color and 3d. Depending on the options given, one of the following will be called: pmdb_write_dx(), pmdb_write_bw_dx(), pmdb_write_2d_dx(), pmdb_write_2d_bw_dx(), pmdb_write_sur_dx(), or pmdb_write_bw_sur_dx(). 
- refine sphere (x,y,z) r
- refine box (x1,y1,z1) (x2,y2,z2)
Call the refdref library to refine at all vertices which fall within the given region. For a sphere refinement, (x,y,z) is the center of the sphere and r is the radius. For a box refinement, the 2 points given are the opposite corners of a box in which refinement is to take place. The files refdref.inp, which gives the parameters to the refinement/derefinement library, and the file meshname.xmt_txt, which is the Parasolid model description file, must exist in the working directory to use the refinement operators. 
- refine percentage pct
Call the refdref library to mark for refinement a percentage of all vertices in the mesh. pct should be a value between 0 and 1 to indicate what portion of vertices should be marked for refinement. Note that this does not mean an increase by a factor of pct - in fact, the growth in mesh size will be several times greater. 
- coarsen sphere (x,y,z) r
- coarsen box (x1,y1,z1) (x2,y2,z2)
Call the refdref library to mark for coarsening all vertices which fall within the given region. For a sphere refinement, (x,y,z) is the center of the sphere and r is the radius. For a box refinement, the 2 points given are the opposite corners of a box in which refinement is to take place. 
- weight sphere (x,y,z) r n
- weight box (x1,y1,z1) (x2,y2,z2) n
Set the weights for all elements in the given region to n. These weights are used rather than the region count to determine workloads during load balancing. Again, for a sphere refinement, (x,y,z) is the center of the sphere and r is the radius. For a box refinement, the 2 points given are the opposite corners of a box in which refinement is to take place. 
- checklinks
Call the PMDB link validity-checking routines. pmdb_check_links() is called. 
- checkmesh
Call the MeshTools mesh validity-checking routines. M_checkAdj() is called.

Load balancing parameter setting: 

- PMDB_LB_SEL_METHOD        <method>
- PMDB_LB_MAX_ITER          <max_iter>
- PMDB_LB_MAX_INTERNAL_ITER <max_iter>
- PMDB_LB_DEBUG_LEVEL       <level>
- PMDB_LB_TOLERANCE         <tol>
- PMDB_LB_PRINT_MIGSTATS    <boolean>
- PMDB_LB_PRINT_ITBTIMES    <boolean>
- PMDB_LB_PRINT_ZOLTANTIMES <boolean>
These commands set various paramters for PMDB's Iterative Tree Balancing algorithm or PMDB Zoltan interface. Each of these results in a call to pmdb_set_load_balance_params(). Valid values for each are described in the PMDB User's Manual. 
- load_balance
Do Iterative Tree Balancing based on the previously set load balancing paramters. This command will result in a call to pmdb_load_balance(). 
- repartition
Call Hugues DeCougny's parallel repartitioning function. This does a global, parallel repartitioning using Inertial Recursive Bisection. 
- parmetis type
Call one of the ParMetis parallel repartitioning functions. The argument "type" specifies which of the methods to use. See the scorec2metis documentation for details. 
- zoltan "param" "value"
- zoltan
These use PMDB's interface to the Zoltan Dynamic Load Balancing Library. WIth two string arguments, this command sets the Zoltan parameter "param" to the value specified by "value". With no arguments, this command performs a Zoltan load balancing and PMDB migration to achieve the new distribution. By default, the PMDB Zoltan interface uses Octree Load Balancing with Hilbert indexing and a maintained octree structure. 
- migstats [ reset | print | output filename ]
migstats reset resets the PMDB internal migration stats counters. It can be called before a refinement, load-balance, or other operation which may include a migration step to obtain detailed information about the time spent and number of messages transmitted during migration.. migstats print will print out the stats since the last migstats reset call. migstats output filename will write the stats since the last reset call to a file filename. 
- modeler [ shapes | parasolid | smd | null]
Select which modeler you wish to use. smd and null are always available, but provide limited or no real information, respectively. The others require commercial modelers to be linked, and are likely to be unavailable in many circumstances. 
- sleep seconds
Put the process to sleep for seconds seconds. This is useful to attach a debugger to a process started in a parallel environment. 
- echo [ all | pid | master ] "message"
Echo a message to standard output. The second argument indicates which processes are to perform the echo. all means all processes should print, master means only the master process, and a process ID number means just that process. A missing second argument indicates that the message should be printed by only the master process.

Enhancements

I'd like to add ability to do some more simple refinements and maybe a few of the other PMDB operations I have not yet implemented in PMDBtool. Suggestions are welcome.

E-mail domain: cs.williams.edu, username: terescoj -- Thu Jan 23 22:12:23 EST 2003