Cart3D Home
home news images pubs c3dTeam
whatIsCart3D?
surfaceModeling
meshGen?
flowSolvers?
postprocess?
mailList?
betaTest?
licensing?


    Mesh Generation


  What is "cubes"?
  What is new in cubes?
  What input files does cubes require?
  What is "autoInputs"?
  Usage - cubes
  How do I run a 2D case?
  Tell me more about prespecified adaptation regions.
  File Format of meshes produced by cubes
  Further Documentation
What is "cubes"?
Cubes  is a mesh generation program which produces topologically unstructured, adaptively refined, Cartesian  meshes around any geometry or configuration that may be described by a collection of simplicial polyhedra (closed surface triangulations - the output of intersect works fine) The source is written in ANSI C and makes extensive use of bitwise operators to minimize memory requirements and maximize speed. 

Features:

  • Gross memory usage typically ~50Mb/million cells 
  • Speed is well in excess of 10,000,000 cells/min on a typical (2013-era) laptop or desktop. 
  • Geometry based adaptive cell division
  • Option for users to limit total # cells & max allowable memory 
  • Multiple region (split-cells) handled automatically 
  • The ability to prespecify mesh adaptation in certain regions or on particular components
  • Remesh using previously created or adapted meshes as a cell-density map while adding in additional refinement in particular regions or on certain components.



       (top)
HSCT configuration 5M cells
5M cell mesh around a HSCT configuration
HSCT configuration 5M cells
side view - zoom box on nacelle region
HSCT configuration 5M cells
closeup near nacelle.
   What's new in cubes?
In v1.5 we've introduced a "-remesh" option that allows cubes to use previously created meshes as a meshing template for relative cell densities. For example, if you have an adapted mesh from aero.csh, You can simply remesh it to make the whole thing finer, change the domain size, put in more background divisions, or even manually add specific refinement regions. This is also handy if you've used Cart3D's adjoint-based adaptation to build an adapted mesh on a small shared-memory system and you want to use that mesh as the basis for a large distributed memory run (using MPI). Using the adapted mesh as a cell-density map, you easily create a much finer mesh that harnesses all the knowledge that the adjoint provided about relative cell density requirements, and then launch a large distributed memory simulation using MPI.  This is also a great tool for adding in a refined region in the wake when an initially steady simulation starts to become unsteady as the mesh gets adaptively refined. This example shows you more detail on remeshing.

   A few tips?
Experienced users can make use of a couple of handy features in cubes to for both greater control and a more streamlined meshing process. All command line options are listed in the usage statement below.
    Automatic reordering:  "% cubes -reorder" will reorder the mesh before it ever hits your disk. This is completely equivalent to running the standalone reorder program, but you skip ever writing the un-reordered mesh, and go straight to Mesh.R.c3d. Since CPU speeds are improving faster than disk speed, writing the mesh has been taking an increasing amount (relative) time in the past few years, Writing out  the mesh at the end of cubes just to read it back in in the first step of reorder seemed like a complete waste of time,  so now you can do it direct. Doing the reorder on-the-fly within cubes does mean that the whole mesh needs to reside in memory at the same time as all the other data structures that cubes needs, so this option does increase the memory requirements of cubes by a bit, but this consumption is not severe, and nobody's complained yet, since cubes has a very tiny memory footprint to start with.
    Sharp Feature Refinement: You can additional refinement sweeps that just target sharp features in your geometry (sharp edges, ridges, etc). This argument takes an integer which says how many additional refinement sweeps to do. Invoke it with "%cubes -sf %d" where %d is an integer. Usually "-sf 1" or (at most) "-sf 2" is sufficient.
(top)

   What input files does cubes require?
Cubes requires 2 files to get going:
  1. An input file controlling the mesh you want to make (only 7 entries! ).  
  2. Input surface triangulations are read in as a Cart3D "wetted surface triangulation" which may contain any number of components.  Entry #1 in the cubes input file takes the name of the triangulation you're gonna mesh. 

Optionally, you can include a "prespecified adaptation region" file, usually called preSpec.c3d.cntl. Entries in this file can be used to direct cubes to refine more in certain regions of the domain click here to learn more about prespecified adaptation regions, or here to see a sample.
(top)

   What is "autoInputs"?
The "autoInputs" utility automatically generates the input.c3d and preSpec files that cubes needs to get going. This utility benefited greatly from beta-testing and we strongly recommend its use by both novice and experienced users alike.  Basically you hand autoInputs your geometry and a rough idea of how big you want the mesh to be and it will produce an input.c3d and preSpec.c3d.cntl file that you can use to mesh. Overall, autoInputs is very handy for getting going in short order. The preSpec.c3d.cntl files that autoInputs produces are quite detailed, and include preSpec boxes for the entire configuration, and smaller boxes for each component. Like the rest of the utility programs in Cart3D, the executable for autoInputs is located in $CART3D/bin/$CART3D_ARCH/. To get a usage statement, type "% autoInputs -" (the trailing "‐" will get you the usage statement, as with all executables in the package).

  Usage - autoInputs
% autoInputs -
   Usage: autoInputs [ argument list ]
 Options:
    -t %s       Input '*.tri' file name <Components.i.tri>
    -r %F       nominal mesh radius <default = 30.>
    -nDiv %d    nominal # of divisions in background mesh <default: 5>
    -maxR %d    Max Num of cell refinements to perform <default: 11>
    -symmX      Halfbody mesh in X
    -symmY      Halfbody mesh in Y
    -symmZ      Halfbody mesh in Z
    -halfBody   Input geometry is a half-body
    -pre %s     file name for preSpec control file <preSpec.c3d.cntl>
    -i   %s     file name for mesh input control file <input.c3d>


(top)

  Usage - Cubes
 
% cubes -
   Usage: cubes [ argument list ]
  Options:
            -- Meshing Options--
      -maxR %d    Max number of refinements (overrides input file)
      -a %f       Angle threshold (deg) for geom refinement <25 deg>
      -b %d       Number of layers of buffer cells <3>
      -pre %s     Prespecified adapt region filename <None>
      -d %f       Angle (deg) for directional refinement (aniso only) <10 deg>
      -Internal   Mesh the *interior* of the geometry
      -mesh2d     Make 2D mesh in X-Y, no refinement in Z
      -I          Restrict cells to isotropic division only
      -remesh     Set cell density from "refMesh.{mg.c3d,c3d.Info}"
      -reorder    Reorder output mesh in space-filling curve order
      -sfc %c     Mesh order: H=Peano-Hilbert, M=Morton <H>
      -verify     Verify that all cut cells close
     
           -- Advanced Options--
      -sf %d      Number of additional levels at sharp edges
      -weight     Area-weight triangles in divide criteria
      -TPC %d     Adapt based on # of triangles-per-cutCell
      -vtest      Special vtest for buffering
      -lin %s     Linearize cut-cells for specified design variable
      -try_exact  (if -N specified) Use Newton solve to hit -N exactly
     
           -- I/O Options--
      -i %s       Input file name <input.c3d>
      -o %s       Output file name <Mesh.c3d>
      -no_file    Suppress output file
      -v          Verbose mode ON
      -quiet      Don't make excessive noise
      -mem        Report memory usage (auto on with -v)
      -h          Print history of # of cells with refinement (auto on with -v)
      -Dunset     Dump Tecplot file <unset.dat>
      -Dcut       Dump Tecplot file <cutcells.dat>
      -Dflow      Dump Tecplot file <flowcells.dat>
      -Dsolid     Dump Tecplot file <solidcells.dat>
      -Dsplit     Dump Tecplot file <splitcells.dat>
      -Daniso     Dump Tecplot file <anisocells.dat>
      -Xcut %d    Number of X=const cut planes <cutPlanes.dat>
      -Ycut %d    Number of Y=const cut planes <cutPlanes.dat>
      -Zcut %d    Number of Z=const cut planes <cutPlanes.dat>
     
           -- Memory Options--
      -memLim %f  Target memory usage (in MB) of final mesh
      -N %d       Target final number of Cartesian cells
      -no_est     Don't estimate memory requirements (slower, less compact)
     
           -- (Deprecated)--
      -P                 
      -T                 
      -ascii
      -STARS      Record intermediate refinement history             
             
(top)
  How do I run a 2D case?
2D cases can be run by making a "slab-like" domain in x-y that is only 1-cell deep (in z). Then use the "-mesh2d" command-line flag to suppress cell refinement in z. The result is a mesh which is adapted in x-y only, and is only 1-cell across. The NACA 0012 example in $CART3D/cases/samples/naca0012/ is designed to illustrate the setup and running of 2D problems.


  File Format of Meshes produced by Cubes
The file format used by Cart3D to store meshes relies heavily upon the fact that the meshes are Cartesian to store meshes in a highly compressed format. This produces quite small mesh files, but the format takes a little explanation. For users who wish to use Cart3D meshes in other applications, or wish to write their own visualization software for these meshes, this format is described in the *pdf document fileformat.pdf (50kb) and an ansi-C I/O library is available for use.  If you're thinking of writing code to read Cart3D meshes (or flowCart's checkpoint files) we generally encourage you to download a copy of the Cart3D I/O library (NASA OpenSource) from the NASA Software Catalog which makes working with these files much easier.

(top)
  Further Documentation
Many of the algorithms in cubes are described in:
AIAA Paper 97-0196: Robust and Efficient Cartesian Mesh Generation for Component-Based Geometry  35th AIAA Aerospace Sciences Meeting, Reno NV Jan, 1997.  (1.7Mb, acrobat format)
(top)

Questions?   Visit Cart3D Discuss,   or  Contact Us
Last update December, 2024.