NEM_SLICE(1)

NAME
nem_slice - generate a load-balance file from an ExodusII geometry file

SYNOPSIS
nem_slice [ -h ] [ -V ] [ -a inpfile ] [ < -n | -e > -v -m machine_desc -l loadbal_desc -s eigensolv_desc ] [ -w weighting_desc ] [ -g group_list ] [ -f ] [ -c ] [ -o outfile ] [ exoIIfile ]

DESCRIPTION
nem_slice reads in a FEM description of the geometry of a problem from an ExodusII file, exoIIfile , generates either a nodal or elemental graph of the problem, calls Chaco to load balance the graph, and outputs a NemesisI load-balance file.

OPTIONS
The -h option causes nem_slice to print out usage information. If the -h option is specified all other options are ignored.

The -V option causes nem_slice to print out the version number. If the -V option is specified all other options are ignored.

If the -a option is specified all parameters will be set from an ASCII input file. Other command line options may be used with -a and such options will override anything respecified in the ASCII input file.

The -n option specifies that a nodal decomposition should be performed on the input FEM mesh, while the -e option specifies that an elemental decomposition should be performed. One of either -e or -n is required.

The -v option is used to indicate that you wish to output an ExodusII file which will allow you to visualize the load balance results. If the mesh consists of one type of element then the visualization is done by element blocks. If the mesh consists of mixed element types then the visualization is done by assigning nodal results variables to each FEM node in the mesh, the value of which corresponds to the processor ID that node is assigned to.

The -m option is used to describe the parallel architecture for which the load balance will be performed. There are currently three choices for this option, mesh for an n-dimensional mesh architecture, hcube for a hypercube architecture, or cluster for a cluster architecture. All machine type specifications require a sub-option giving the dimension(s) of the machine, and thus the number of processors, for which the load balance is to be performed.

The -l option is used to specify which method to utilize in generating a load balance for the given problem. In addition, a sub-option of kl can be specified if Kernighan-Lin refinement is desired and the main method does not use KL by default. Another sub-option is the number of sections to use (see the Chaco User's Guide for further information). This can be specified with the sub-option, num_sects=value. An additional sub-option requires that the load balanced domains are connected. This can be specified with the sub-option, cnctd_dom. Supported methods for load balancing are:

multikl
spectral
inertial
linear
random
scattered
zpinch
infile=filename
The last option, infile, reads the assignment vector from and input file. When using this option, no other load balancing is performed. In addition, the is a sub-option, outfile=filename, that will write out the assignment vector after the load balancing is complete.

The -s option is used to specify parameters for the eigensolver, if the method utilizes an eigensolver. Parameters which can be specified are:

tolerance=value
use_rqi
vmax=value

The -o option gives the name of the NemesisI output file. By default the output file name is generated from the input file name with different additions depending on the method being used for load balancing and the number of processors for which the load balance was generated.

The -w option is used to specify how to weight the graph of the problem once it is generated. Currently read , eb , and edges sub-options are supported. The read sub-option allows the reading in of weights from an ExodusII file. Nodal values are read for nodal decompositions and elemental values for elemental decompositions. Along with the read sub-option other sub-options which can be specified are the name of the variable, either nodal or elemental depending on the method requested, as it exists in the ExodusII input file. This variable can either be specified via it's name with the var_name sub-option. Or it can be specified with it's index via the var_index sub-option. In addition the time index from which to read the given variable can also be specified with the time_index sub-option. The eb sub-option is used to give a specific weight to a given element block. The format to give block n a weight of m is
    eb=n:m
If the sub-option eb comes after the read sub-option in the weighting specifications, then the value for the element block overwrites the values read in from the ExodusII file. If the eb sub-option comes before the read sub-option, then it is ignored. The edges sub-option is used to turn on edge weights for an elemental decomposition. The default is that edge weights are not calculated. This sub-option is ignored for a nodal decomposition.

The -g option allows the user to break up the element blocks into groups that will be passed seperately to Chaco. If the group descriptor has white spaces in it, then it must be enclosed in quotes ("). The following rules apply to the descriptor:
    - Blocks are grouped using the slash "/" character.
    - Ids are separated with white space, comma, or by the hyphen "-" character. The hyphen, "-", is used to include all elment blocks between the two given ID's.
    - Any blocks not included in the list, are added to a separate group.
    - Duplicates in the list are permitted, but the last group to which a block is placed is where the block will go.
    - Block IDs not in the exodus file are quietly ignored.

The -c option turns off some of the error checking that nem_slice does while finding elemental communication maps.

INPUT FILE FORMAT
The optional ASCII input file closely mimics the command line options. The file consists of a sequence of keys, each with a tab or ``='' separated value. The order of the keys is not significant and a line beginning with a ``#'' is considered to be a comment. The following keys are recognized by nem_slice :

    Input ExodusII File
    Output NemesisI File
    Graph Type
    Decomposition Method
    Solver Specifications
    Machine Description
    Weighting Specifications
    Misc Options

The case of the words forming a key is not significant.

COMMAND LINE EXAMPLES
To obtain a nodal load balance for a 2D mesh parallel computer with processors arrayed in a 10x20 grid using multi-level decomposition:

nem_slice -n -m mesh=10x20 -l multikl geom.exoII

For the same problem to be run on a 5 dimensional hypercube use:

nem_slice -n -m hcube=5 -l multikl geom.exoII

To generate an elemental based load balance using a spectral method, with KL refinement, for a 3D mesh architecture, with the RQI eigensolver and quadrisection:

nem_slice -e -m mesh=10x5x2 -l spectral,kl,num_sects=1 -s use_rqi

To generate a nodal based load balance with Inertial+KL with weights read from nodal results contained in an ExodusII file use:

nem_slice -n -m mesh=10x5x2 -l inertial,kl -w read=weights.exoII,vindx=1,time=2

ASCII INPUT FILE EXAMPLE
    (See the file "input-ldbl" distributed with the executable)

SEE ALSO
The Chaco User's Guide Version 1.0; B. Hendrickson, R. Leland; Sandia Report SAND93-2339, Nov. 1993

NemesisI: A Set of Functions for Describing Unstructured Finite Element Data on Parallel Computers; G. Hennigan, J. Shadid

NOTES
nem_slice attempts to be smart about parsing command line, or ASCII input file, options. However, some errors may sneak through, in which case Chaco is relied upon for error detection.

AUTHORS
Gary L. Hennigan, Sandia National Labs, Dept. 9221
Matthew M. St. John, Sandia National Labs, Dept. 9221
John N. Shadid, Sandia National Labs, Dept. 9221