Sculpt

Sculpt is a separate parallel application designed to generate all-hex meshes on complex geometries with little or no user interaction. Sculpt was developed as a separate application so that it can be run independently from Cubit on high performance computing platforms. It was also designed as a separable software library so it can be easily integrated as an in-situ meshing solution within other codes. Cubit provides a front end command line and GUI for the Sculpt application. The command will build the appropriate input files based on the current geometry and can also automatically invoke Sculpt to generate the mesh and bring the mesh back to Cubit.

Preparing to Use Sculpt

Platforms

Sculpt is available for Windows, Mac and Linux operating systems.

Sculpt Installation

Sculpt is a stand-alone executable, separate from Cubit. In order for Cubit to start up Sculpt, it must be on your system and accessible to Cubit. The default installation of Cubit should install files in the correct locations for this to occur. Check with Cubit support if it did not come with your installation or you are not able to locate it or any of its supporting applications.

To run Sculpt from Cubit, four executable files are needed:

To view the current path to these executables that Cubit will use, issue the following command from the Cubit command window

 Sculpt Path List

See the Sculpt Path Command for more info on setting and customizing these paths.

The following image illustrates the process flow when the sculpt command is used in Cubit.

Sculpt process flow

For the Sculpt meshing process, a set of files, including a facet-based stl file are written to disk. The sculpt application is then started up which in turn invokes mpiexec to start up multiple instances of psculpt in parallel. psculpt then performs the meshing and writes one exodus file per processor. These files can then be combined using epu and then imported back into Cubit for viewing.

Setting your Working Directory

When using the Sculpt command in Cubit, several temporary files will be written to the current working directory. Because of this, it is important to set your working directory before using Sculpt to a desired location where you want these files placed.

Sculpt Command

The Sculpt Command in Cubit invokes the sculpt application. You can designate the target geometry, which can be existing volumes or blocks within the current Cubit run or imported from external files (e.g., STL, diatom, or microstructure files). The command syntax for preparing a model for Sculpt is as follows:

Sculpt [parallel]

Geometry Options

{[volume <ids>] [block <ids>] [stl_file "<filename.stl>"] [diatom_file "<filename.diatom>"] [input_vfrac "<filename.e>"] [input_micro "<filename.tec>"] [input_cart_exo "<filename.e>"] [input_spn "<filename.spn>"]}

[spn_xyz_order "<0,1,..5>"] [input_stitch "<filename.st>"] [stitch_field "<field_name>"] [stitch_timestep {<timestep_value>|first|last}] [stitch_timestep_id <timestep_ID>] [stitch_info]

Process Options

[processors <value>] [fileroot "<rootfilename>"] [{OVERWRITE|no_overwrite}] [absolute_path] [{EXECUTE|no_execute}] [{COMBINE|no_combine}] [{IMPORT [unique_genesis_ids]|no_import}] [{SHOW|no_show}] [{CLEAN|no_clean}] [{gen_input_file <string>|no_gen_input_file}] [{debug <value>] [quiet] [preview]

Grid Options

[{size <value>|autosize <value>}] [box {align|location <options>|expand <value>}] [{xintervals|nelx} <value> {yintervals|nely} <value> {zintervals|nelz} <value>] [input_mesh "<filename.g>"] [input_mesh_material <value>] [input_mesh_pamgen "<filename.pam>"]

Mesh Options

[void <value>] [void_block <value>] [separate_void_blocks] [stair <value>] [htet <value>] [htet_material <value>] [htet_method <value>] [periodic <value>]

Smoothing Options

[smooth <value>] [csmooth <value>] [num_laplace <value>] [max_opt_iters <value>] [opt_threshold <value>] [curve_opt_thresh <value>] [max_pcol_iters <value>] [pcol_threshold <value>] [max_gq_iters <value>] [gq_threshold <value>] [max_deg_iters <value>] [deg_threshold <value>] [geo_smooth_max_deviation <value>]

Improve Options

[pillow <value>] [pillow_surfaces] [pillow_curves] [pillow_curve_layers <value>] [pillow_curve_thresh <value>] [pillow_boundaries] [pillow_smooth_off] [defeature <value>] [min_vol_cells <value>] [defeature_bbox] [defeature_iters <value>] [capture <value>] [capture_angle <value>] [capture_side <value>] [thicken_material <value>...] [thicken_void <value>] [remove_bad <value>] [wear_method <value>] [crack_min_elem_thickness <value>] [temp_use_sipe_depth <value>] [min_num_layers <value>]

Adapt Options

[adapt_type <value>] [adapt_threshold <value>] [adapt_levels <value>] [adapt_material <value>...] [adapt_export] [adapt_non_manifold] [adapt_load_balance]

Boundary Condition Options

[gen_sidesets <value>] [material_name <value>... <string>...] [sideset_name <value>... <string>...] [nodeset_name <value>... <string>...] [sideset_definition <value>... <string>...] [nodeset_definition <value>... <string>...] [free_surface_sideset <value>...] [match_sidesets <value>...] [match_ss_nodeset <value>...]

Output Options

[exodus <string>] [large_exodus] [xtranslate <value>] [ytranslate <value>] [ztranslate <value>] [xscale <value>] [yscale <value>] [zscale <value>] [volfrac_file <string>] [quality <string>] [write_geom] [write_mbg] [compare_volume] [compute_ss_stats]

Controlling the Execution of Sculpt in Cubit

The following command options can be used to control the execution of Sculpt from within Cubit when used with the sculpt command. Follow the links above for other options that control he behavior of the sculpt algorithms and methods.

volume <ids> | block <ids>

List of volumes or blocks to include in the mesh. One file containing a faceted representation (STL) per volume will be generated and saved in the current working directory to be used as input to Sculpt. Each volume will be treated as a separate material within sculpt and a conforming mesh will be generated where volumes touch. If the Block command is used, one file per block will be used. Each block represents a separate material in Sculpt.

fileroot '<root filename>'

Root of file names for output. When the sculpt command is executed, Cubit will generate multiple files in the working directory used for input to the Sculpt application. The '<root filename>' will be used as the basis for naming these files.

processors <value>

Specify the number of processors that MPI will use to execute the Sculpt application. If not specified, the maximum number of available processors on the local machine will be used up to a maximum of 16.

OVERWRITE | no_overwrite

By default, Cubit will overwrite an existing set of files with the same '<root filename>'. To over-ride, use the no_overwrite option.

absolute_path

By default, Cubit will write the relative path names of files used in the .run and .diatom files. To force absolute path names to be written, use the absolute_path option

EXECUTE | no_execute

By default, Cubit will attempt to run sculpt in parallel on the machine Cubit is currently running on. To generate just the required input to run Sculpt at a later time or on another machine, use this option. A file of the form <root filename>.run will be generated in the current working directory. (for example "model.run"). Executing the .run file from the linux command line should run sculpt in parallel. It can also be used to run sculpt on a cluster where a Cubit executable may not be available.

size <value> | autosize <value>

The size option is the absolute cell size for the Cartesian grid and is the same as the cell_size option in sculpt. The autosize option is a value between 0 and 10. It represents a model independent size where 1 is the small size and 10 is large. This is the same scaling factor used in Cubit's auto sizing but is divided by ten. A size value will be computed from the selected autosize and used as the absolute cell size for the base Cartesian grid.

box location <options>

When using a Cartesian grid as the overlay grid definition, the location options define the bounds of the Cartesian grid. The first Location <option> defines the minimum Cartesian coordinate of the grid and the second, the maximum. The <options> can be any valid method for defining a coordinate location in cubit. In most cases the position option can be used. The default is computed as an enclosing bounding box with 2.5 additional cells on each side.

Note that the xmin, ymin, zmin, xmax, ymax, zmax options can also be used for specifying the bounds of the Cartesian grid from the command line.

COMBINE | no_combine

If the no_combine option is used, following execution of Sculpt, the resulting exodus meshes will not be combined using the epu seacas tool. Otherwise the default will automatically combine the meshes generated by each processor into a single mesh. Note that epu should be installed on your system and the path to epu defined using the sculpt path command. Epu is a code developed by Sandia National Laboratories and is part of the SEACAS tool suite. It combines multiple Exodus databases produced by a parallel application into a single Exodus database. The epu program should be included with distributions of Cubit beginning with Version 15.0.

IMPORT | no_import

If the no_import option is used, following execution of Sculpt, the result will be not be imported into Cubit as a free mesh. The default IMPORT option will automatically import the mesh that was generated in Sculpt. If the no_combine option has been used, then multiple free meshes will be imported with duplicate nodes and faces at processor domain boundaries. Otherwise a single free mesh, the result of the epu code, will be imported. Note that the resulting mesh will not be associated with the original geometry, however Block (material) definitions will be maintained. In addition, a separate group will be generated for each imported mesh (One per processor). The default will automatically import the mesh following mesh generation in Sculpt.

SHOW | no_show

If the no_show option is used, while the external Sculpt process is running, no ouput from the Sculpt application will be displayed to the command window. Otherwise, the default SHOW is used and output from the Sculpt application will be echoed to the Cubit command window. This option is only effective if the no_execute is not used.

CLEAN | no_clean

If the clean option is used, temporary files generated during the sculpt command will be deleted. This includes any exodus mesh files, .stl, .diatom, .log and .run files. The default for this option is CLEAN, therefore, use the no_clean option to keep any temporary files generated as part of the current Sculpt run.

gen_input_file <file name> | no_gen_input_file

An input file with the given file name will be generated when the command is executed. This is a text file containing all sculpt options used in the command. The input file is intended to be used for batch execution of sculpt. To run sculpt from the operating system command line you would use the -i option. For example: sculpt -i myinputfile.i -j 4 where myinputfile.i is the name of the input file specified with the gen_input_file option and -j 4 is the number of processors to use.

debug <value> The debug option is used only as a developer debugging tool. It will set the debug processor and sleep upon execution to allow a debugger to be attached to the process.

quiet

The quiet option used as an option in the sculpt command will suppress output from the sculpt application to the Cubit output window.

preview

When used with the sculpt command, the preview option will print the contents of the sculpt input file to the Cubit output window, based on the currently defined options in the sculpt command. It will not execute sculpt.

Sculpt Help Command

Help about any of the Sculpt options can be printed to the output window using the following command:

Sculpt [parallel] print_help [<"sculpt_option">]

where <"sculpt_option"> is any valid sculpt application option listed above.

Sculpt Path Command

The command for letting Cubit know where the Sculpt and related applications are located is:

 Sculpt [Parallel] Path [List|Psculpt|Epu|Mpiexec]

This command defines the path to psculpt, epu and mpiexec on your system. In most cases, however, these paths should be automatically set provided Sculpt was successfully installed with your Cubit installation. The list option will list the current paths that Cubit will use for these tools. If an alternate path to these executables is desired, it is recommended that this command be used in the .cubit initialization file so that it wont be necessary to define these parameters every time Cubit is run.

Sculpt Mesh Quality Control

In most cases, the Sculpt tool can be used without adjusting default values. Depending on the characteristics of the geometry to be meshed, the default values may not yield adequate mesh quality. Upon completion, Sculpt reports to the command line, a summary of the mesh that was generated. This includes a summary of the mesh quality. Care should be taken to review this summary to ensure the minimum mesh quality is in a range suitable for analysis.

The element metric used for computing mesh quality in Sculpt is the Scaled Jacobian. This is a value between -1 and 1 that is a relative measure of the angles at the element's nodes. A value of 1 indicates a perfect 90 degree angle between each of its edges. In most cases a value less than zero, or negtive Jacobian element, indicates an unusable mesh. Sculpt's default settings try to achieve a minimum Scaled Jacobian of 0.2, which is normally usable in most analysis. The following discussion provides several options for adjusting the model or Sculpt parameters to help improve mesh quality.

  1. Locating poor mesh quality: When the Sculpt mesh has been imported back into CUBIT it is a good idea to display the element quality. You can do this with variations of the following commands:

     quality hex all scaled jacobian
    quality hex all draw mesh

    Identify regions where hexes are poor quality and zoom in to these regions.
  2. Modifying the geometry: Zooming in to poor quality elements may reveal that the mesh does not adequately represent the underlying geometry. In some cases you may find that small features, or small gaps between parts may be on the order of the size of the Sculpt cell size. If these features are not important to the analysis, you may consider using Cubit's geometry modification tools to remove features or close small gaps.
  3. Modifying the cell size: In cases where small geometric features or gaps are important to the simulation, it may be necessary to use a smaller base cell size. Use the size or autosize input parameters or increase the numbers of intervals. Normally to adequately capture a feature you would want the cell size to be no greater than about 1/3 to 1/2 the size of the smallest feature you would want to represent in the simulation.
  4. Turning on Pillowing for multiple materials: For models that have more than one material that share an interface, unless the geometry is precisely aligned with the global axis, it is usually a good idea to turn on pillowing. Pillowing automatically inserts an additional layer of hexes at interface boundaries to improve mesh quality. Without pillowing may notice inverted or poor quality elements at curve interfaces where 2 or more materials meet.
  5. Modifying smoothing parameters: Sculpt includes a tiered approach to smoothing to improve element quality. It starts by applying smoothing to all nodes in the mesh and progressively restricts the smoothing operations to only those nodes that fall below a user-defined scaled Jacobian threshold. Default numbers of iterations and thresholds for each smoothing phase have been tuned for general use, however it may be worthwhile to adjust these parameters. The three smoothing phases include: Observing the mesh quality output to the command line following each smoothing iteration can provide some insight on the effect of modifying smoothing parameters.
  6. Creating degenerate hexes: Some geometries will not permit a usable mesh with a traditional all-hex mesh. Sculpt includes the option to automatically and selectively collapse element edges to improve low-quality elements. The max_deg_iters and the deg_threshold values are used to control the creation of degenerates. Degenerate elements are treated as standard hex elements, but use repeated nodes in the eight-node connectivity array.
  7. Creating hex-dominant mesh Another option for avoiding mesh quality issues is to generate a few tet elements in the mesh using the htet option. With this option you can specify a scaled Jacobian threshold value below which hexes will be converted to tet elements. The interface between hex and tet elements is managed by an automatically defined set of nodesets and sidesets that describe where multi-point constraints will be applied.
  8. Defeaturing The defeature option does an initial filter on the cells of the base grid and attempts to reassign the material ID for cells that meet certain criteria. These are cases where a small grouping of cells form a small volume, or where protrusions exist that would otherwise be difficult or impossible to mesh with good quality elements. By reassigning the cells in these locations, in many cases it will allow the mesh to be acceptable. This operation may result in small changes to the boundary or surface definitions, however usually small enough to still be a reasonable approximation.

Sculpt Examples

The following examples use this simple geometry. Execute these commands prior to performing the example Sculpt command line operations

sphere rad 1
sphere rad 1
vol 2 mov x 2
cylinder rad 1 height 2
vol 3 rota 90 about y
vol 3 mov x 1
unite vol all

Sculpt example geometry

Figure 1. Geometry created from the above commands and used for the following examples.

Basic Sculpt

This example illustrates use of Sculpt with all default options. So that we can view the result, we will also use the overwrite, combine and import options.

sculpt volume 1
draw block all

The result of this operation is shown in Figure 2. For this example, behind the scenes, Cubit built an input file for Sculpt, ran it on 4 processors, combined the resulting 4 meshes, and subsequently imported the resulting mesh into Cubit. Note that Volume 1 remains "unmeshed" and we have created a free mesh that is not associated with a volume. The result of any Sculpt command is always an unassociated free mesh.

Meshed example geometry

Figure 2. Free mesh generated from sculpt command

Size and Bounding Box

This example illustrates the use of the size and box options

delete mesh
sculpt volume 1 size 0.1 box location position -1.5 0 -1.5 location position 1 1.5 0
draw block all

In this case we have used the size option to define the base cell size for the grid. We have also used the box option to define a bounding box in which the mesh will be generated. Any geometry falling outside of the bounding box is ignored by Sculpt. Figure 3 shows the mesh generated with this command.

Meshed example geometry

Figure 3. Sculpt "box" option limits the extent of the generated mesh.

Meshing the Void

In this example we illustrate the use of the void option:

delete mesh
sculpt volume 1 size 0.1 box location position -1.5 0 -1.5 location position 1 1.5 0 void 1
draw block all

The result is shown in figure 4. Notice that this example is precisely the same as the last with the exception of the addition of the void option. Mesh is generated in the space surrounding the volume out to the extent of the bounding box. In this case, an additional material block is defined and automatically assigned an ID of 2. The nodes and element faces at the interface between the two blocks are shared between the two materials.

Meshed example geometry

Figure 4. Sculpt "void" operation generates mesh outside the volume.

Automatic Sideset Definition

In this example we illustrate the use of the gen_sidesets option.

Generating sidesets on the free mesh with Cubit: Sideset boundary conditions can be manually created on the resulting free mesh from Sculpt using the standard Sideset <sideset_id> Face <id_range> syntax. The Group Seed command is also useful in grouping faces based on a feature angle to be used in a single sideset.

Generating sidesets in Sculpt: Sculpt also provides several options for defining sidesets as part of the Sculpt run. The following illustrates one option:

delete mesh
sculpt volume 1 size 0.1 box location position -1.5 0 -1.5 location position 1 1.5 0 void 1 gen_sidesets 2
list sideset all
draw sideset all

Once again we use the same syntax but add the gen_sidesets 2 option to automatically generate a series of sidesets. The list command should reveal that 10 sidesets were defined for this example with IDs 1 to 10. Figure 5 shows the result of the draw command showing all of the sidesets in different colors. Note that for the gen_sidesets 2 option, sidesets are created with the following criteria:

See the gen_sidesets option above for a description of other options for generating sidesets in Sculpt.

Meshed example geometry with side sets

Figure 5. Automatic sidesets created using Sculpt

Running Sculpt Stand-Alone

This example illustrates how to set up the files necessary to run Sculpt as a stand-alone process. This can be done on the same desktop machine or moved to a larger cluster machine more suited for parallel processing.

Begin by setting your working directory to a location that is convenient for placing example files

 cd "path/to/my/sculpt/examples"

Next we issue the basic sculpt command to mesh the volume

delete mesh
sculpt volume 1 processors 8 fileroot "bean" over no_execute no_clean

In this case, we used the no_execute option which does not invoke the Sculpt application. Instead it will write a series of files to the working directory. The fileroot option defines the base file name for the files that will be written; in this case "bean". We also use the processors option to set the number of processors to be used to 8. Finally, since the default clean option will remove temporary files after execution of sculpt, we use the no_clean option to ensure they will persist.

To see the files that Cubit placed in the working directory, bring up a terminal window on your desktop and change directories to the current working directory (ie. cd path/to/my/sculpt/examples). A directory listing should reveal 3 files as shown in Figure 6.

Directory listing

Figure 6. Directory listing of files written from Cubit

The following describes the purpose of each of the resulting files:

Sculpt command line

Figure 7. Unix command line for running Sculpt generated by Cubit

To run sculpt on the same machine, from the terminal window in your current working directory you would issue the following command:

./bean.run

If Sculpt is to be run on a different machine, copy the files in the working directory to the other machine and issue the same command. Remember to change the path to the mpiexec and psculpt executables to match those on the new machine. For running on cluster machines that have scheduling of resources, check with your system administrator for how to submit a job for running.

After running Sculpt, Figure 8 shows the resulting files that would be written to the current working directory.

Sculpt command line

Figure 8. 8 Exodus files were generated and placed in working directory

Note that 8 exodus files have been generated, 1 from each processor. These files can be used by themselves or used as-is for use in a simlation, or they can be combined into a single file. The exodus files produced by Sculpt include all appropriate parallel communication information as defined by the Nemesis format. Nemesis is an extension of Sandia's Exodus II format that also includes appropriate parallel communication information.

To combine the resulting exodus files into a single file, we can use the epu tool. Epu should be included in your Cubit distribution, but may require you to set up appropriate paths for it to be recognized. To run epu on this model, use the following command from a unix terminal window:

epu -p 8 bean.diatom_result

The result should be a single file with the name bean.diatom_result.e. The mesh in this file can then be imported into Cubit. Switch back to your Cubit application and from the command line type the following command:

import mesh "bean.diatom_result.e" no_geom

The result should be the same mesh we generated previously that is shown in Figure 2.

Meshing Multiple Materials With Sculpt

This example illustrates using Sculpt to mesh models with multiple materials. To begin with, we will modify our current model by adding some additional volumes. Use the following commands:

delete mesh
cylinder rad 0.5 height 3
cylinder rad 0.5 height 3
vol 5 mov x 2

The resulting geometry should look like the image in Figure 9.

Geometry for multi-material

Figure 9. Geometry used to demonstrate multiple materials with Sculpt

Use this geometry to generate a mesh using Sculpt.

sculpt volume all size 0.075
draw block all

The resulting mesh should look like the image in Figure 10.

Mesh of multi-material

Figure 10. Mesh generated on multiple materials

Notice that one mesh block per volume was created. We should also note that no boolean operations were performed prior to building the mesh with Sculpt. In fact, volumes 4 and 5 were significantly overlapping volume 1. This would be an invalid condition for normal Cubit meshing operations. Figure 11 shows a cut-away image of the mesh using the Clipping Plane tool.

Mesh of multi-material

Figure 11. Cut-away of mesh generated on multiple materials

We should also note that imprint/merge operations typically needed, were also not required. While it is usually best to avoid overlaps to avoid ambiguities in the topology, Sculpt is able to generate a mesh giving precedence to the most recently defined materials. Merging is performed strictly by geometric proximity. Volumes closer than about one half the user input size will normally be automatically merged.

Next, we will examine the mesh quality of the free mesh. The following command will display a graphical representation of the Scaled Jacobian metric.

quality hex all scaled jacobian draw mesh

The result is shown in Figure 12. Note the elements (colored red) at the interface between materials are unacceptable for simulation. This is caused by the Sculpt algorithm projecting nodes to a common curve interface shared by the materials.

Mesh quality

Figure 12. Mesh quality of multi-material mesh.

In most cases, the poor element quality at material interfaces can be improved by using the pillow option. Adding this option will direct Sculpt to add an additional layer of elements surrounding each surface. To see the result of pillowing, issue the following commands:

delete mesh
sculpt volume all size 0.075 over combine import pillow 1
quality hex all scaled jacobian draw mesh

Mesh quality

Figure 13. Mesh quality of multi-material mesh using pillow option

The resulting mesh is showed in Figure 13. Note the improved mesh quality at the shared curve interface. A closer look at the mesh, shown in Figure 14. reveals the additional layer of hexes surrounding each surface that allows for improved mesh quality when compared with Figure 11. When generating meshes with multiple materials that must share common interfaces, the pillow option is usually recommended.

Pillow layers

Figure 14. Cutaway of mesh reveals the additional layer of hexes surrounding each surface when the pillow option is used.