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            
  --periodic                 -per        Generate periodic mesh                         
  --check_periodic           -cp   <arg> Check for periodic geometry                    
  --check_periodic_tol       -cpt  <arg> Tolerance for checking periodicity             
  --periodic_axis            -pax  <arg> Axis periodicity is about                      
  --periodic_nodesets        -pns  <arg> Nodesets ids of master/slave nodesets          
  --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)

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

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.

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:

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:

Generate Periodic Mesh

Command: periodic     Generate periodic mesh

Input file command:   periodic
Command line options: -per

Command Description:

Generates a periodic mesh for either Cartesian or unstructured mesh input. Ensures that resulting mesh nodes and faces are precisely matching on opposite sides of the mesh.

Unstructured mesh input: When used with the --input_mesh option opposite sides of the mesh must be identified using pairs of leading and trailing nodesets using the --periodic_nodesets (-pns) option. Nodes in the nodeset pairs must be separated by a constant translation or rotation. If a rotation is used between leading and trailing nodesets, the --periodic_axis (-pax) option must be used. If not used, then the transformation is assumed to be pure translation. Input geometry is assumed to be periodic with a period equal to that of the input mesh. Results from non-periodic geometry used with the periodic option may be unpredictable. The following is an example of an input file that uses the periodic option on an unstructured input mesh:

   BEGIN SCULPT
      diatom_file = geometry_file.diatom
      input_mesh = input_exodus_file.g
      exodus_file = output_exodus_file
      smooth = to_geometry
      capture = 5
      capture_angle = 10
      free_surface_sideset = 1000
      gen_sidesets = input_mesh_and_free_surfaces
      periodic = true
      periodic_nodesets = 3224 3225
      periodic_axis = 0 0 0 0 1 0
   END SCULPT

Cartesian grid input: This option is often used for computational materials modeling. Sculpt can generate a true periodic mesh in a representative volume element (RVE) where meshes on all opposite faces of the RVE will precisely match. When used with a Cartesian grid, the --periodic_nodesets and --periodic_axis options are ignored. The following is an example sculpt input file that utilizes the --periodic option on a Cartesian grid with geometry defined in a diatom file. It also utilizes the --adapt_type option to automatically refine and the gen_sidesets = RVE option to generate sidesets at the six RVE faces.

   BEGIN SCULPT
      diatom_file = spheres_periodic.diatom
      xmin = -18.705510
      ymin = -18.705510
      zmin = -18.705510
      xmax = 18.705510
      ymax = 18.705510
      zmax = 18.705510
      nelx = 38
      nely = 38
      nelz = 38
      periodic = true
      defeature = 1
      min_vol_cells = 10
      adapt_type = vfrac_average
      adapt_levels = 2
      adapt_threshold = 0.00001
      gen_sidesets = RVE
      exodus_file = spheres_periodic
      mesh_void = true
   END SCULPT

Geometry Requirements: In order to generate a valid periodic mesh, the input geometry must also be periodic and the bounding box parameters should span exactly one period of the geometry. To check the periodicity of the geometry and prescribed bounding box, see the check_periodic option. Note: The resulting mesh at the boundaries of the Cartesian grid (RVE) will not be projected to the planes of the bounding box. The result will be a "ragged" boundary in order to maintain periodicity between nodes on opposite sides of the mesh. Also note that results from the use of the periodic option may be undefined or unstable when used with non-periodic input geometry.

Periodic geometry used for example described in diatom file. RVE boundary shown with respect to the geometry.

Resulting periodic mesh generated from example input.

Six faces of the RVE from above example illustrating periodicity on a 32 processor decomposition. Note that top three images are a mirror image of the bottom three images.

Check for periodic geometry

Command: check_periodic     Check for periodic geometry

Input file command:   check_periodic <arg>
Command line options: -cp <arg>
Argument Type:        on, off, only 
Input arguments: off (0)
                 on (1)
                 only (2)

Command Description:

When using the periodic option with a Cartesian base grid, the input geometry must be periodic with respect to the grid bounding box in order to meet the minimum requirements of a valid periodic mesh. The bounding box must span exactly one period in each dimension. If this requirement is not met, a valid mesh may still be generated, however, periodicity will not be guaranteed. The check_periodic option is used to check this requirement. See also check_periodic_tol to set the tolerance for checking periodicity. Options:

ON: The check_periodic option is ON by default to ensure periodicity is enforced. Sculpt will fail if the geometry and bounding box do not meet the requirements for periodicity.
OFF: Turning this option OFF will by-pass this check and attempt to generate the mesh even if periodic requirements are not met.
ONLY: The ONLY option will perform a check for periodic requirements and report diagnostics. An exodus file (or files) will be produced with the name "check_periodic.0.0.x.x". A stair-step mesh of the domain will be produced with an additional 2 blocks: 999 and 998. Block 999 shows master cells that are not matched. Block 998 shows paired ghost cells that should have the same volume fraction as those in block 999, but do not. Sculpt will immediately stop execution after producing the "check_periodic.0.0.x.x" mesh. Note that 2 additional layers on all sides of the Cartesian grid will be present in the mesh. These are used internally in Sculpt for parallel ghosting.

The check_periodic option is ignored if the periodic option is OFF or set to false.

Tolerance used for periodic check

Command: check_periodic_tol     Tolerance for checking periodicity

Input file command:   check_periodic_tol <arg>
Command line options: -cpt <arg>
Argument Type:        floating point value

Command Description:

Used on conjunction with the check_periodic option. It specifies a tolerance value when checking periodicity. Check periodic option checks the difference between computed volume fractions for cells on the overlay grid that are separated by exactly one period. The periodic tolerance is the allowable volume fraction difference between cells separated by one period. Default value is 1e-6.

Periodic Mesh Axis

Command: periodic_axis     Axis periodicity is about

Input file command:   periodic_axis <arg>
Command line options: -pax <arg>
Argument Type:        six floating point values

Command Description:

For an unstructured base grid, specifies an axis about which the nodes in the master (leading) nodesets will be rotated about to produce the slave (trailing) nodesets. Six floating point numbers are specified, the first three define the origin of the axis and the last three define the axis direction. This option must be used with --periodic (-per), --periodic_nodesets (-pns), and --input_mesh (-im) options. If the --periodic (-per) option is used without the --periodic_axis option, the transformation between leading and trailing nodesets is assumed to be pure translation.

Periodic Nodeset Ids

Command: periodic_nodesets     Nodesets ids of master/slave nodesets

Input file command:   periodic_nodesets <arg>
Command line options: -pns <arg>
Argument Type:        integer(s) >= 0

Command Description:

For an unstructured base grid, specifies the master-slave (leading-trailing) nodeset pairs. Master nodesets should be able to be translated or rotated about a specified axis to produce the nodes in the slave nodesets. Nodesets must be specified in pairs, where each master (leading) nodeset corresponds to a single slave (trailing) nodeset. Each nodeset pair must maintain an identical translation or rotation. If a rotation is used, the axis and origin of rotation must be specified with the --periodic_axis (-pax) option. This option should be used with --periodic (-per), --periodic_nodesets (-pns), and --input_mesh (-im) options.)

Unstructured input mesh used to generate periodic mesh. Matching leading and trailing nodesets are defined in the exodus file.

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) 
Input arguments: cth (0)
                 cth (1)
                 r3d (2)

Command Description:

Sets the method used for computing volume fractions from geometry input. Two 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.