Cubit 16.12 User Documentation
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.
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 Parallel Path List
See the Sculpt Parallel Path Command for more info on setting and customizing these paths.
The following image illustrates the process flow when the sculpt parallel command is used in Cubit.
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.
When using the Sculpt Parallel 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.
The Sculpt Parallel 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]
{[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]
[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]
[{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>"]
[void <value>] [void_block <value>] [separate_void_blocks] [stair <value>] [htet <value>] [htet_material <value>] [htet_method <value>] [periodic <value>]
[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>]
[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_type <value>] [adapt_threshold <value>] [adapt_levels <value>] [adapt_material <value>...] [adapt_export] [adapt_non_manifold] [adapt_load_balance]
[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>...]
[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]
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.
Root of file names for output. When the sculpt parallel 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.
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.
By default, Cubit will overwrite an existing set of files with the same '<root filename>'. To over-ride, use the no_overwrite option.
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
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.
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.
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 parallel 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.
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.
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.
The quiet option used as an option in the sculpt command will suppress output from the sculpt application to the Cubit output window.
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.
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.
The command for letting Cubit know where the Sculpt and related applications are located is:
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 Parallel Path [List|Psculpt|Epu|Mpiexec]
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.
Identify regions where hexes are poor quality and zoom in to these regions.quality hex all scaled jacobian
quality hex all draw mesh
The following examples use this simple geometry. Execute these commands prior to performing the example Sculpt Parallel 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
Figure 1. Geometry created from the above commands and used for the following examples.
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 parallel
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.
Figure 2. Free mesh generated from sculpt command
This example illustrates the use of the size and box options
delete mesh
sculpt parallel 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.
Figure 3. Sculpt "box" option limits the extent of the generated mesh.
In this example we illustrate the use of the void option:
delete mesh
sculpt parallel 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.
Figure 4. Sculpt "void" operation generates mesh outside the volume.
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 parallel 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.
Figure 5. Automatic sidesets created using Sculpt
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 parallel command to mesh the volume
delete mesh
sculpt parallel 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.
Figure 6. Directory listing of files written from Cubit
The following describes the purpose of each of the resulting files:
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.
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.
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.
Figure 9. Geometry used to demonstrate multiple materials with Sculpt
Use this geometry to generate a mesh using Sculpt.
sculpt parallel size 0.075
draw block all
The resulting mesh should look like the image in Figure 10.
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.
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.
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 parallel size 0.075 over combine import pillow 1
quality hex all scaled jacobian draw mesh
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.
Figure 14. Cutaway of mesh reveals the additional layer of hexes surrounding each surface when the pillow option is used.