Sculpt Input Data Files

Options for specifying input files to Sculpt. Sculpt uses a method for representing geometry based upon volume fractions defined on a Caresian grid. Sculpt will accept facet-based (STL) or analytic (diatom) geometry, but will first convert the input geometry to the required volume fraction decription before generating the hexahedral mesh. Various formats for volume fraction data can also be imported directly into Sculpt and used as the basis for hex meshing. The following formats are currently supported in Sculpt:

• STL (stl_file)
• diatom (diatom_file)
• Volume Fractions
  • Exodus element variables (import_vfrac)
  • Exodus blocks (import_cart_exo)
  • Ascii Voxel Data (import_spn)
  • Ascii Volume Fraction Data (import_micro)

Input Data Files 		--input 	-inp
  --stl_file,		-stl <args>	Input STL file
  --diatom_file,	-d <args>	Input Diatom description file
  --input_vfrac,	-ivf <args>	Input from Volume Fraction file base name
  --input_micro,	-ims <args>	Input from Microstructure file
  --input_cart_exo,	-ice <args>	Input from Cartesian Exodus file
  --input_spn,		-isp <args>	Input from Microstructure spn file
  --input_mesh,		-im <args>	Input Base Exodus mesh
  --lattice,		-l <args>	STL Lattice Template File

Sculpt Command Summary

Command: stl_file     Input STL file

Long Name:     --stl_file 
Short Name:     -stl 
Argument Type:   file name with path 

File name of a single STL (facet geometry) file to be used as input. Either an stl_file or diatom_file designation should be included to run Sculpt. The stl_file option will support a single STL file. To use multiple STL files, where each file represents a different material, use the diatom_file file option where multiple file names may be specified.

It is recommended that STL files used as input to Sculpt be "water-tight". While in many cases non-watertight geometries will be successful, unexpected or incorrect results may result. It is recommended practice to use Cubit to first import the STL geometry and allow the sculpt parallel command to write a new STL geometry file for use in Sculpt. Cubit's sculpt parallel command will attempt to stitch and repair any triangle facets that are not completely closed. Other commercial tools are available for STL geometry that may be effective in repairing the geometry prior to use in Sculpt.

Command: diatom_file     Input Diatom description file

Long Name:     --diatom_file 
Short Name:     -d 
Argument Type:   file name with path 

File name of a diatom file to be used as input to Sculpt. Both stl_file and diatom_file cannot be used simultaneously. A diatom file is a constructive solid geometry description containing primitives for generating a full geometric definition of the model. Diatoms are commonly used as input to Sandia's CTH and Alegra codes. Multiple STL files can also be defined in a Diatom file. The following is a simple example of a diatom file that would read 3 different STL files:

        diatoms
          package 'blue_material'
            material 1
            insert stl
              file = 'blue_part1.stl'
            endinsert
            insert stl
              file = 'blue_part2.stl'
            endinsert
          endpackage
          package 'red_material'
            material 2
            insert stl
              file = 'red_part1.stl'
            endinsert
          endpackage
        enddiatom
    

For a full description of the diatom format see the CTH or Alegra documentation.

Command: input_vfrac     Input from Volume Fraction file base name

Long Name:     --input_vfrac 
Short Name:     -ivf 
Argument Type:   base file name with path 

Sculpt can optionally take an exodus file containing volume fraction data stored as element variables. Normally the exodus file has initially been written using the --volfrac_file (-vf) option. Since the exodus file will be a Cartesian grid spread accross multiple processors, the base filename for the parallel series of exodus files is used as the argument for this command. The input volume fraction file(s) would be used instead of an STL or diatom file. Since computing volume fractions from geometry can be time consuming, precomputing the volume fractions and reading them from a file can be advantageous if multiple meshes are to be generated from the same volume fraction data.

Command: input_micro     Input from Microstructure file

Long Name:     --input_micro 
Short Name:     -ims 
Argument Type:   file name with path 

A microstructure file is an ascii text file containing volume fraction data for each cell of a Cartesian grid. The format for this file includes header information followed by data for each cell. The following is an example:

    TITLE = triple line system
    VARIABLES = x y z, phi_1, phi_2, phi_3
    ZONE i = 2 , j = 2 , k = 2
    0.0000       0.0000       0.0000      0.5000      0.5000      0.0000
    1.0000       0.0000       0.0000      0.3333      0.3333      0.3334
    0.0000       1.0000       0.0000      1.0000      0.0000      0.0000
    1.0000       1.0000       0.0000      0.0000      1.0000      0.0000
    0.0000       0.0000       1.0000      0.2000      0.4000      0.4000
    1.0000       0.0000       1.0000      0.6000      0.1000      0.3000
    0.0000       1.0000       1.0000      0.0000      0.0000      1.0000
    1.0000       1.0000       1.0000      0.9000      0.0000      0.1000
    

The header information should contain the following:

TITLE: any descriptive character string

VARIABLES: a list of variables separated by spaces or commas. It should include x, y, z as the first three variable names. The remaining names are arbitrary. The number of variable names listed must correspond to the number of data values for each cell of the Cartesian grid.

ZONE: Specify the number of cells in the i, j and k directions (corresponding to x, y, and z respectively)

The body of the file will contain one line per cell of the grid. The first three values correspond to the centroid location of a cell in the grid. The remaining values represent volume fractions for the cell for each variable listed. The sum of the volume fractions for each individual cell should be 1.0

Currently this format assumes that cell sizes are exactly 1.0 x 1.0 x 1.0 and the minimum cell centroid location is always 0.0, 0.0, 0.0. This results in a Cartesian grid with minimum coordinate = (-0.5, -0.5, -0.5) and maximum coordinate = (i-0.5, j-0.5, k-0.5). If a size other than 1x1x1 is required consider using the scale and/or translate options.

Example usage of this command is as follows:

      sculpt -j 8 -ims my_micro_file.tec -p 1
    

Smoothing: Sculpt will set automatic defaults for smoothing if user options have not been defined. These include:

    --smooth 9 (surface smoothing option - no surface projection)
    --csmooth 2 (curve smoothing option - hermite interpolation)
    

These options will generally provide a smoother curve and surface represention but may not adhere strictly to the volume fraction geometric definition. To over-ride the defaults, consider using the following options:

    --smooth 8 (surface smoothing option - projection to interpolated surface)
    --csmooth 5 (curve smoothing option - projection to interpolated curve)

    

Pillowing: For most 3D models it is recommended using pillowing since triple junctions (curves with at least 3 adjacent materials) will typically be defined where malformed hex elements would otherwise be generated. Surface pillowing (option 1) is usually sufficient to remove poor quality elements at triple junctions.

Command: input_cart_exo     Input from Cartesian Exodus file

Long Name:     --input_cart_exo 
Short Name:     -ice 
Argument Type:   file name with path 

An exodus mesh containing a Cartesian grid of elements can also be used as the source of a sculpt mesh. For this option the following conditions must be met:

1. A single (non-parallel) exodus II format file.
2. Contains only hex elements configured as a Cartesian grid.
3. All hex elements must be exactly equilateral cubes.
4. Each hex element has been assigned to exactly one block. (Any number of blocks may be defined in the file)

Provided these conditions are met, sculpt will treat each block as a separate material and generate a smooth conforming mesh between the materials. This option is useful for converting a stair-step mesh into a smooth conforming mesh. The resulting sculpt mesh will have the same dimensions as the original exodus mesh, but will add layers of hexes at material interfaces.

Example usage of this command is as follows:

      sculpt -j 8 -ice my_cartesian_file.e -p 1
    

Smoothing: Sculpt will set automatic defaults for smoothing if user options have not been defined. These include

    --smooth 9 (surface smoothing option - no surface projection)
    --csmooth 2 (curve smoothing option - hermite interpolation)
    

These options will generally provide a smoother curve and surface represention but may not adhere strictly to the volume fraction geometric definition. To over-ride the defaults, consider using the following options:

    --smooth 8 (surface smoothing option - projection to interpolated surface)
    --csmooth 5 (curve smoothing option - projection to interpolated curve)
    

Pillowing: For most 3D models it is recommended using pillowing since triple junctions (curves with at least 3 adjacent materials) will typically be defined where malformed hex elements would otherwise be generated. Surface pillowing (option 1) is usually sufficient to remove poor quality elements at triple junctions.

Command: input_spn     Input from Microstructure spn file

Long Name:     --input_spn 
Short Name:     -isp 
Argument Type:   file name with path 

A .spn file is an optional method for importing volume fraction data into sculpt for meshing. This format is a simple ascii text file containing one integer per cell of a Cartesian grid. Each integer represents a unique material identifier. Any number of materials may be used, however for practical purposes, the number of unique materials should not exceed more than about 50 for reasonable performance.

An example file containing a 3 x 3 x 3 grid with 2 materials may be defined as follows:

        1 1 2 1 2 1 1 1 1
        1 2 2 1 2 2 1 1 2
        2 1 1 1 2 1 1 2 2
    

Any unique integer may be used to identify a material. All cells with the same ID will be defined as a continuous block with the same exodus block ID in the final mesh. All integers should be separated by a space or newline. The number of integers in the file should exactly correspond to the size of the Cartesian grid. The dimensions of the Cartesian grid must be specified on the command line as part of the input. The following is an example:

        sculpt -j 8 -x 10 -y 24 -z 15 -isp "my_spn_file.spn" -p 1
    

        for (i=0; i<nx; i++)
          for (j=0; j<ny; j++)
            for (k=0; k<nz; k++)
               // read next value from file
    

Where nx, ny, nz are the number of cells in each Cartesian direction. The initial size of the Cartesian grid will be exactly nx X ny X nz with the minimum coordinate at (0.0, 0.0, 0.0). If a size other than the default is required, consider using the scale and/or translate options.

Smoothing: Sculpt will set automatic defaults for smoothing if user options have not been defined. These include:

    --smooth 9 (surface smoothing option - no surface projection)
    --csmooth 2 (curve smoothing option - hermite interpolation)
    

    --smooth 8 (surface smoothing option - projection to interpolated surface)
    --csmooth 5 (curve smoothing option - projection to interpolated curve)
    

Pillowing: For most 3D models it is recommended using pillowing since triple junctions (curves with at least 3 adjacent materials) will typically be defined where malformed hex elements would otherwise be generated. Surface pillowing (option 1) is usually sufficient to remove poor quality elements at triple junctions.

Command: input_mesh     Input Base Exodus mesh

Long Name:     --input_mesh 
Short Name:     -im 
Argument Type:   file name with path 

Option to import an Exodus file to use as the base mesh for Sculpt. Sculpt's meshing procedure requires a base mesh from which geometry is recovered and captured. The default base mesh is a Cartesian grid that is defined by specifying a bounding box and intervals. The input_mesh option permits a general hexhedral mesh to be used as the base mesh instead of a Cartesian grid. This option currently supports a serial Exodus file containing HEX8 elements with a single block. Three different options are supported for describing the geometry:

stl_file: A single file containing a water-tight faceted description of the geometry. Note that only the portion of the STL file completely contained within the base mesh will be represented in the final mesh.

diatom_file: May contain analytic descriptions of geometric primitives and/or references to multiple STL files.

Element Variables: The geometry may also be described by element variables in the Exodus file. Element variables should represent material volume fractions where the sum of element variables for any one cell should be between 0.0 and 1.0. Any number of element variables may be used where each unique variable defined will describe an element block in the final Exodus mesh produced. if the sum of element varables is less than 1.0 for any one element, a void material will be assumed and removed from the base mesh unless the mesh_void option is used.

Command: lattice     STL Lattice Template File

Long Name:     --lattice 
Short Name:     -l 
Argument Type:   file name with path 

Generate a lattice structure from a hex mesh. This command takes the name of an STL format template file which defines the lattice over a unit cube. To generate a valid lattice structure, the facets should be symmetric to the three coordinate planes. The lattice structure will be transformed and copied into each hex of the mesh. The result will be an STL file containing lattice geometry for the mesh.

This option currently requires the name of an exodus mesh on which to define the lattice. Use the --exodus_file (-e) option to specify its path. The current implementation is limited to one block, however if a second block is contained in the Exodus file it will be treated as a solid and stl facets will be generated at the skin of the block.

The name of the output STL file may also be defined by using the --stl_file (-stl) option. If no stl file is specified, the output will use the name of the input exodus file with the extension "_lattice.stl" appended. In addition to the full lattice geometry, an additional file containing only the lattice from the first layer of hexes will be written. This may be useful in reducing the size of the STL file for visualization purposes only. The name of this file will be the name of the full STL geometry file with the extension ".vis.stl" appended.

The following is an example input file using the lattice option:

      BEGIN SCULPT
        lattice = lattice_template.stl  $contains unit cube with triangles
        exodus_file = file.e $ hex mesh containing one or two element blocks
        stl_file = file.stl $ name of output stl file
      END SCULPT

    

Note that this option is currently limited to serial execution (-j 1)