Sculpt Process Control

Options for controlling the execution of Sculpt. Sculpt is a parallel application that uses MPI to distribute and build the hex mesh on multiple processors. The -j or num_procs option is normally used to specify the number of processors to use. Sculpt will write a separate exodus file for each processor, which can be joined into a single file using the epu utility. While any number of processors may be used, you would normally use a -j value less than or equal to the number of cores available on your hardware.

Sculpt options can be specified directly from the command line using the "short" commands, or from an input file where the longer forms of the commands are used. Since an input file can be commented and modified, it is generally the recommended method for running Sculpt.

Process Control              -pc     --process
  --num_procs                -j    <arg> Number of processors requested                      
  --input_file               -i    <arg> File containing user input data                     
  --debug_processor          -D    <arg> Sleep to attach to processor for debug              
  --debug_flag               -dbf  <arg> Dump debug info based on flag                       
  --quiet                    -qt         Suppress output                                     
  --print_input              -pi         Print input values and defaults then stop           
  --version                  -vs         Print version number and exit                       
  --threads_process          -tpp  <arg> Number of threads per process                       
  --iproc                    -ip   <arg> Number of processors in I direction                 
  --jproc                    -jp   <arg> Number of processors in J direction                 
  --kproc                    -kp   <arg> Number of processors in K direction                 
  --build_ghosts             -bg         Write ghost layers to exodus files for debug        
  --vfrac_method             -vm   <arg> Set method for computing volume fractions           

Sculpt Command Summary

Number of Processors

Command: num_procs     Number of processors requested

Input file command:   num_procs <arg>
Command line options: -j <arg>
Argument Type:        integer > 0

Command Description:

The number of processors that Sculpt will use to generate the mesh. For a structured, Cartesian base grid, the domain will be automatically divided into roughly equal sized rectangular regions based on this value.

For unstructured input (see --input_mesh), to utilize more than one processor, the base mesh must first be docomposed into the same number of regions specified by num_procs. The decomp tool, part of the Sandia, SEACAS tool suite can be used to break up an exodus mesh into multiple regions suitable for sculpt input.

An independent mesh of a portion of the domain is generated on each processor. Continuity across processor boundaries is maintained with MPI (Message Passing Interface). Each processor will write a separate Exodus II file to disk containing its portion of the domain. The Sandia SEACAS tool, epu can be used to join parallel files into a single file if desired.

If not specified on the command line, the number of processors used will be 1.

For additional control on the arrangement of processor domains on a Cartesian base grid, see arguments iproc, jproc, kproc.

Input File

Command: input_file     File containing user input data

Input file command:   input_file <arg>
Command line options: -i <arg>
Argument Type:        file name with path

Command Description:

Rather than specifying a complicated series of arguments on the command line, an input file may also be used. An input file is a simple text file containing all arguments and parameters to be used in the current sculpt run. Input files are normally expected to have a ".i" extension. Arguments used in the input file are limited to the Long Names indicated for each command.

User comments can also be made anywhere in the file but must follow a "$" sign. The argument assignments that are intended to be read must be contained within a "begin sculpt" and "end sculpt" block. All arguments may use upper or lower case and can optionally use "=" between the command and its parameter. The following is an example input file:

  BEGIN SCULPT
    stl_file = "mygeom.stl"
    cell_size = 0.5
    exodus_file = "mymesh"
    mesh_void = true
  END SCULPT

The following is an example of using an input file with sculpt:

  sculpt -j 4 -i myinput.i

Note that the number of processors (-j) should always be used on the command line and cannot be included in the input file. Relative or absolute paths for files may also be used.

Debug Processor

Command: debug_processor     Sleep to attach to processor for debug

Input file command:   debug_processor <arg>
Command line options: -D <arg>
Argument Type:        integer >= 0

Command Description:

Used for debugging. All processes will sleep until the designated process is attached to a debugger. Note: value of 0 corresponds to first processor, 1 to second, etc.

Debug Flag

Command: debug_flag     Dump debug info based on flag

Input file command:   debug_flag <arg>
Command line options: -dbf <arg>
Argument Type:        integer >= 0 
Input arguments: off (0)
                 lost_nodes (1)
                 non-manifold (2)
                 defeature (3)
                 thickening (4)
                 initial-projections (5)
                 reversal (6)
                 gq-color (8)
                 gq-full (9)
                 hostname (10)
                 test_large_global_ids (11)
                 use_bbox_for_unstructured (12)
                 allow_input_mesh_sidesets (13)

Command Description:

Used for debugging. Set flag to dump specific info based on the following:

0 (off) Default, No debug output

1 (lost_nodes) Dump processor lost node info

2 (non-manifold) Export Non-manifold resolution state as exodus file after each inner and outer iteration.

3 (defeature) Export Defeature state as exodus file after each inner and outer iteration.

4 (thickening) Export the Thickened st:wqate as exodus file after each material has been thickened.

Guaranteed Quality:

5 (initial-projections) Turn off initial minimizer projection.

6 (reversal) Use Non-manifold reversal case

7 Combine debug_flag 5 and 6

8 (gq-color) Use guaranteed quality laplacian color smoothing

9 (gq-full) Combine debug_flags 5,6 and 8

10 (hostname) Display the host name for each processor

11 (test_large_global_IDs) starts the global node and element ID numbering at INT_MAX (2^31) for testing large_exodus option.

12 (use_bbox_for_unstructured) Use the xmin, ymin, ... options to limit the domain on an input_mesh

13 (allow_input_mesh_sidesets) Don't restrict use of gen_sidesets = 6, 7 or 9 if using parallel. (This may result in poor elements at proc boundaries).

Quiet

Command: quiet     Suppress output                        

Input file command:   quiet
Command line options: -qt

Command Description:

Suppress any output to the command line from Sculpt as it is running.

Print Input

Command: print_input     Print input values and defaults then stop

Input file command:   print_input
Command line options: -pi

Command Description:

Display all input parameters and defaults used in the current Sculpt run to the output window and then stop. No mesh (or volume fractions) will be generated.

Version

Command: version     Print version number and exit

Input file command:   version
Command line options: -vs

Command Description:

Prints Sculpt version information and exits.

Threads Per Processor

Command: threads_process     Number of threads per process

Input file command:   threads_process <arg>
Command line options: -tpp <arg>
Argument Type:        integer > 0

Command Description:

This option is currently experimental and under development. Sculpt may use shared memory parallelism to improve performance. When built with the Kokkos library, some algorithms in sculpt will use shared memory parallel threads in addition to MPI distributed memory parallelism (MPI+X). Currently this option is implemented only for surface and volume Laplacian smoothing algorithms. This option may not be available requiring a custom build of sculpt to be used. Check with developers if you would like to use this option.

Number of processors in I

Command: iproc     Number of processors in I direction

Input file command:   iproc <arg>
Command line options: -ip <arg>
Argument Type:        integer > 0

Command Description:

Arguments iproc, jproc and kproc provide user control over the processor decomposition in I, J, and K directions respectively. iproc * jproc * kproc must equal the number of processors specified on the command line using the -j option. In some cases, where it is known that significant refinement will be done in a localized region of the domain, it may be worth manually specifying the number of cell layers, or intervals that each processor will contain. This should provide rough processor load balacing so that regions with an expected large number of elements will have a smaller physical domain, but roughly similar element counts. This may avoid single processor memory limitations on large HPC machines. To specify processor intervals, optionally, the exact interval count in I, J, K directions should be specified. The number of intervals specfied for each direction should be the value of iproc, jproc, and kproc respectively. In addition, the sum of the intervals in each direction should equal the user specified nelx, nely and nelz values respectively. For example, for a 24 processor (-j 24) arrangement with nelx = nely = 28 and nelz = 27, one possible arrangment of processors would be as follows:

    nelx = 28
    nely = 28
    nelz = 27
    iproc = 2 14 14
    jproc = 2 14 14
    kproc = 6 7 6 5 4 3 2

For this example the I and J directions are equally subdivided into 2 processors with 14 intervals in both directions. The K direction, however is subdivided into 6 processors, where the intervals are progressively thinner, starting with 7 intervals at the bottom (smallest z) and ending with 2 intervals at the top (largest z). Note that the number of intervals in any direction must always be at least 2 or greater. If processor intervals are omitted, Sculpt will attempt to roughly equally space the intervals in each direction. If at least one direction of intervals is detected in the input, then all directions should be specified. Note that this option is only available when using a Cartesian base grid specification and cannot be used with an unstructured base grid using the input_mesh option.

Number of processors in J

Command: jproc     Number of processors in J direction

Input file command:   jproc <arg>
Command line options: -jp <arg>
Argument Type:        integer > 0

Command Description:

    nelx = 28
    nely = 28
    nelz = 27
    iproc = 2 14 14
    jproc = 2 14 14
    kproc = 6 7 6 5 4 3 2

Number of processors in K

Command: kproc     Number of processors in K direction

Input file command:   kproc <arg>
Command line options: -kp <arg>
Argument Type:        integer > 0

Command Description:

    nelx = 28
    nely = 28
    nelz = 27
    iproc = 2 14 14
    jproc = 2 14 14
    kproc = 6 7 6 5 4 3 2

Write the ghost layers for debug

Command: build_ghosts     Write ghost layers to exodus files for debug

Input file command:   build_ghosts
Command line options: -bg

Command Description:

If set, this option will dump the ghost hexes at the boundaries of processor domains to the exodus files. This is used only for debugging.

Volume Fraction Calculation Method

Command: vfrac_method     Set method for computing volume fractions

Input file command:   vfrac_method <arg>
Command line options: -vm <arg>
Argument Type:        integer (1, 2, 3) 
Input arguments: cth (0)
                 cth (1)
                 r3d (2)
                 winding (3)

Command Description:

Sets the method used for computing volume fractions from geometry input. Three options are currently available:

CTH (1): The default method. It uses the CTH third party library from Sandia Laboratories for approximating intersections using an adaptive ray firing method to determine inside-outside status of multiple locations within a grid cell. This method can be used with STL and all valid primitive types defined by the diatom format.

R3D (2): Uses the R3D third party library developed by Los Alamos Laboratories. Machine precision intersection calculations are performed to generate accurate volume fractions from the STL description. This method is valid for STL and diatom input packages specifying STL input files. Non STL format geometry defined in the diatom file will be ignored for this format.

Winding (3): Uses the fast winding number from the igl third party library, which should gracefully handle non-watertight stl files. R&D is in progress.