Contrib gmshFoam

From OpenFOAMWiki

Valid versions: OF version 13.png OF version 14.png OF version 141.png

1 Short description

On-the-fly visualization of the oodles/pitzDaily case by gmshFoam.

A conceptual implementation of a total Gmsh pre/mid/post-processing environment for OpenFOAM. "Conceptual," or "proof-of-concept," because it is still very preliminary. Readers are recommended to read this page up to the final Technical section, where there are lots of footnotes and remarks, before installation.

NOTE: The developer had ceased the maintenance of the codes and the page is only kept for archival reason. Feel free to take over the project if you feel like to do so.

2 Motivation and words of warning

GmshFoam is primalily meant to be a course material for an introductory course in computational engineering. I thought Gmsh is an excellent software to be used in company with OpenFOAM for true starters, because it contains all the necessary peripheral processing stuff in simple user interface with sophisticated graphics. While Gmsh is not as feature-rich as e. g. paraFoam, it generally requires less user interactions to do the same thing. The concept has been turned out to be fairly successful in that even students who had been high-schoolers until a month before can do basic works after a three-hour lecture. I am also finding gmshFoam to be quite usable for solver development, where many small test cases are often run manually.

On the other hand, a major downside of gmshFoam for general usage is, as the Gmsh manual states, its slowness for large-scale problems especially on postprocessing. You may find gmshFoam is sometimes too slow with only ~ 100,000 postprocessing elements. With all these considered, I'm making gmshFoam to be like a lightweight, easy-to-handle and versatile Alphajet, not an F-15 real combat aircraft.

3 Installation

3.1 Prerequisites

  • The gmshFoam package: Download from the Download section below.
  • gmsh-2.0.8-source.tgz: You need the source distribution of Gmsh if you would like to use gmshFoam (the standalone converters, gmsh2ToFoam, foamToGmsh and foamMeshToGmsh, should work without the Gmsh source).
  • The autoconf utility that comes with your Linux distribution if you would like to use gmshFoam.

3.2 Installation procedure

In the following procedure, the gmshFoam and Gmsh packages are assumed to be downloaded into:

  • The gmshFoam package: $WM_PROJECT_USER_DIR/applications/utilities
  • The Gmsh source package: $WM_PROJECT_INST_DIR/$WM_ARCH


1. Setup the OpenFOAM environment.
$ source ~/OpenFOAM/OpenFOAM-1.4.1/.OpenFOAM-1.4.1/bashrc
2. Build the libraries and standalone utilities (YYYYMMDD denotes the release date of the gmshFoam package).
$ cd $WM_PROJECT_USER_DIR/applications/utilities
$ tar -zxf gmshFoam-YYYYMMDD.tar.gz
$ ln -s gmshFoam-YYYYMMDD gmshFoam    <<--- Necessary for gmshFoam to be recognized by FoamX
$ cd gmshFoam
$ ./Allwmake

With this step the followings will be installed:

  • into $(FOAM_USER_APPBIN): gmsh2ToFoam, foamToGmsh, foamMeshToGmsh, gmshFoam (a sh script), gmshFoamMonitor
  • into $(FOAM_USER_LIBBIN): libgmshFoam.so, libgmshMessageStream.so

If you only need converters (gmsh2ToFoam, foamToGmsh and foamMeshToGmsh) you don't have to take extra steps below. The converters should work without Gmsh.

3. Apply the patch included in the gmshFoam package to Gmsh sources, and build/install Gmsh. 

$ cd $WM_PROJECT_INST_DIR/$WM_ARCH
$ tar -zxf gmsh-2.0.8-source.tgz
$ mv gmsh-2.0.8 gmsh-2.0.8-src
$ cd gmsh-2.0.8-src
$ patch -p1 < $WM_PROJECT_USER_DIR/applications/utilities/gmshFoam/gmsh-2.0.8-foam-YYYYMMDD.diff
$ autoconf
$ ./configure --prefix=$WM_PROJECT_INST_DIR/$WM_ARCH/gmsh-2.0.8 \
  --with-foam-prefix=$WM_PROJECT_USER_DIR/applications/utilities/gmshFoam
...
checking for main in -lhdf5... no
checking for main in -lgmshMessageStream... yes    <<--- Indicates the detection of OpenFOAM libraries!
checking for grep that handles long lines and -e... /usr/bin/grep
...
$ make
$ make install
$ cd ..; rm -rf gmsh-2.0.8-src

Please make sure proper OpenFOAM environment variables are set up before building Gmsh because the configure script uses the environment variables to detect the gmshFoam and OpenFOAM libraries. Also, don't forget to run autoconf before running configure.

Note that the options given to configure in the example above are the minimal ones to build Gmsh with OpenFOAM support. You need to give extra appropriate options to build Gmsh with other packages such as Tetgen, Triangle or OpenCASCADE.

The final binary executable will be installed into $WM_PROJECT_INST_DIR/$WM_ARCH/gmsh-2.0.8/bin.

4. Add the path to Gmsh in one of the setup scripts. For example add the following line to the last of $WM_PROJECT_DIR/.bashrc. 

export PATH="$WM_PROJECT_INST_DIR/$WM_ARCH/gmsh-2.0.8/bin:$PATH"

5. Optionally, for OF 1.4.1 users it is recommended to update error.C, error.H and OStringStream.H and rebuild libOpenFOAM.so (run wmake libso under OpenFOAM-1.4.1/src/OpenFOAM) following this thread of the Message Board, since a bug in exception throwing code in error.C crashes gmshFoam while handling exceptions (caused by e.g. invalid field files). It is known that 1.4 also has the same bug, however currently no fix is offered.

3.3 For Cygwin users

To build Gmsh under the Cygwin environment, you need development packages of fltk, gsl, libjpeg and libpng (all available from the Cygwin setup.exe. In the arguments given to the configure script, add --enable-cygwin.

The installation steps might be a bit complicated for average Cygwin users so an OpenFOAM-enabled Gmsh-cygwin precompiled binary is prepared here.

4 Usage

4.1 Gmsh

Format selections in file dialogs.

The version of Gmsh built following the installation procedure above has the capabilities of:

  • direct exporting of generated meshes by OpenFOAM polyMesh format -- by choosing "File" -> "Save As..." and selecting "OpenFOAM polyMesh (*.foam)" as the exporting format. The mesh will be written into the constant directory under the directory with the specified name (the dummy extension .foam will be removed).
  • direct importing of OpenFOAM polyMesh (experimental) -- by choosing the case directory and adding dummy .foam extension to the case directory name. The current version requires a dummy file with the case name + .foam extension to actually exist when reading from "File" -> "Open..." or "Merge...," so specifying the name as a command line option is recommended.
  • direct importing of OpenFOAM fields in a case direcotry as postprocessing views -- by choosing system/controlDict in the "File" -> "Open..." or "Merge..." dialog (optionally you can filter the files in the list by selecting "OpenFOAM case (controlDict)" as the importing format). Of course you can do the same thing by directly specifying the system/controlDict file as a command-line argument when launching Gmsh.
  • the option string foam is also available as an argument of the -format option.

In addition to the original option variables, the followings are available.

  • Mesh.FoamRenumberMesh: Renumber the OpenFOAM mesh for matrix bandwidth compression? (1 = yes (default), 0 = no)
  • PostProcessing.FoamStartTime: The time name where reading the OpenFOAM case starts ("latestTime" for only the latest time). Note that the value must be given as a char-expression. The default is "" (an empty string).
  • As a value given to Mesh.Format option, 34 which stands for polyMesh is available.

4.2 gmshFoam

$ gmshFoam <root> <case> [<.geo file> | -monitor | -mesh | -decomposedMesh]
How to start a case monitoring
interFoam/damBreakFine mesh displayed by decomposedMesh mode. You can set visibility of each decomposed region by selecting Tools->Visibility and...
... selecting mesh partitions on Mesh partitions subpanel with the partition numbers that correspond to the processor numbers assigned to each decomposed mesh. After selection, click Apply.
You can also set the vibility of each decomposed volume/patch/processor boundary within Physical groups subpanel. The numbers enclosed by parentheses denote processor numbers assigned to each entity.

GmshFoam is a wrapper script for Gmsh just like paraFoam is for ParaView, and has five modes depending on the arguments specified.

  • When launched with two arguments of <root> and <case>, Gmsh starts in postprocessing mode and works just as paraFoam.
  • When launched with three arguments of <root>, <case> and a <.geo file>, Gmsh starts in mesh mode, loads the .geo file, sets the default mesh output format to foam and the default output directory to the case directory. In this mode you can simply click "3D" and "Save" buttons to generate a mesh and save it in polyMesh format into the constant subdirectory.
  • When launched with three arguments of <root>, <case> and -monitor Gmsh launches in solver mode with a special solver launching button "OpenFOAM case monitor." By clicking the button and further clicking "Start" of the following launcher dialog, Gmsh starts watching the case directory with the help of gmshFoamMonitor (see below) and visualize the newest field data on-the-fly with the interval specified in the launcher dialog.
  • When launched with three arguments of <root>, <case> and -mesh Gmsh imports polyMesh under constant/polyMesh subdirectory of the case directory. The imported mesh can be exported with whatever formats supported by Gmsh.
  • When launched with three arguments of <root>, <case> and -decomposedMesh Gmsh works as decomposed mesh viewer, i. e. imports polyMesh under all processorx subdirectories of the case directory and displays the merged mesh with assigning each decomposed mesh the mesh partition number which corresponds to the processor number. For details, see the pictures on the right.

4.3 gmsh2ToFoam

$ gmsh2ToFoam <root> <case> <.geo or .msh> [options]

Gmsh2ToFoam is the standalone version of the direct mesh exporter in Gmsh and works without Gmsh. For detailed usage, see the gmsh2ToFoam page.

4.4 foamToGmsh

$ foamToGmsh <root> <case> [-splitTimeStepsByMeshMotion] [-startTime <time>] [-verbosity <verbosity>]

FoamToGmsh is the standalone version of the direct field data importer in Gmsh and works without Gmsh. It converts OpenFOAM fields in a case directory to Gmsh view files of binary format. A view file is created for a field with field name + extension ".pos" under the <case>/Gmsh directory.

  • -splitTimeStepsByMeshMotion: splits the view files every time a mesh motion is detected (by the presence of a "polyMesh/points" file). Actually, the option is a byproduct of a failed attempt to implement moving mesh handling into gmshFoam, so even the author himself don't know what the option is good for (don't worry, the moving mesh handling has been implemented by a different way).
  • -startTime
  • <tt>-verbosity <verbosity></tt>: same as in <tt>gmsh2ToFoam</tt>.

4.5 foamMeshToGmsh

$ foamMeshToGmsh <root> <case> [-verbosity <verbosity>]

<tt>FoamMeshToGmsh</tt> is the standalone version of the direct mesh importer in Gmsh and works without Gmsh. It converts OpenFOAM polyMesh to Gmsh .msh file format version 2.0 that can be converted back to polyMesh by <tt>gmsh2ToFoam</tt> (i. e. patch names, base patch types and cell/face-Zone definitions are retained in the physical group definitions). Usage is same as <tt>foamMeshToFluent</tt> and the resulting .msh file is created under <tt>gmshInterface</tt> subdirectory in the case directory.

4.6 gmshFoamMonitor

The utility is a helper application which is to be launched from the Gmsh solver launcher, thus not meant to be run directly from a shell. Its purpose is to watch the case directory with the specified interval and instructs Gmsh to read and visualize the field data when a new time directory is created.

It reads a dictionary called <tt>gmshFoamMonitorDict</tt> in the <tt>system</tt> subdirectory every time new data is to be visualized, and applies the view options specified by the dictionary so that you can set the viewing angle, clipping planes, field to visualize, etc. For details, please see the example <tt>gmshFoamMonitorDict</tt> below. The example is also included under the <tt>example</tt> directory of the gmshFoam package.

5 Examples

5.1 Generating polyMesh from a .geo

Suppose you are in a case directory, have <tt>myGeometry.geo</tt> under the directory and would like to convert the <tt>.geo</tt> to a polyMesh into <tt>constant</tt> subdirectory. The most conventional way is to generate an intermediate <tt>.msh</tt> by <tt>gmsh -3</tt> and convert it to polyMesh by <tt>gmsh2ToFoam</tt>. 

$ gmsh -3 myGeometry.geo
$ gmsh2ToFoam . . myGeometry.msh

<tt>Gmsh2ToFoam</tt> can perform above if a <tt>.geo</tt> is given instead of a <tt>.msh</tt>. 

$ gmsh2ToFoam . . myGeometry.geo

If you would like to directly export from Gmsh: 

$ gmsh -3 -format foam -o . myGeometry.geo

or, if <tt>myGeometry.geo</tt> has a line <tt>Mesh.Format = 34;</tt>, simply run 

$ gmsh -3 -o . myGeometry.geo

. If you would like to do interactively through GUI, run 

$ gmshFoam . . myGeometry.geo

and hit "3D" and "Save."

5.2 Converting other mesh formats to polyMesh

Suppose you are in a case directory. To convert an I-deas UNV mesh to polyMesh under <tt>constant</tt> subdirectory run 

$ gmsh -3 -format foam -o . myIdeasMesh.unv

and you can do with similar manners for other supported mesh formats.

5.3 Converting a polyMesh to other formats

Suppose you are in a case directory. To convert a polyMesh under <tt>constant</tt> subdirectory to a <tt>.msh</tt> run 

$ foamMeshToGmsh . .

and the resulting <tt>.msh</tt> will be created under <tt>gmshInterface</tt> subdirectory. Or if you would prefer to use Gmsh, run 

$ gmsh -3 -format msh -o myMesh.msh ..foam

(please note two successive dots without whaitespaces in between, where the first dot denotes the current directory and the second one the separator between basename and extension). Similarly, If you would like to convert to I-deas UNV, run 

$ gmsh -3 -format unv -o myIdeasMesh.unv ..foam

and you can do with similar manners for other supported mesh formats.

5.4 Importing a polyMesh into Gmsh

Suppose you are in a case directory. To import a polyMesh under <tt>constant</tt>subdirectory run 

$ gmsh ..foam

(again, please note the two successive dots), or 

$ gmshFoam . . -mesh

. And you can do whatever that can be done for a .msh (conversion, manipulation etc.).

5.5 Viewing decomposed meshes under processorx subdirectories

Suppose you are in a case directory. To view decomposed meshes under all <tt>processorx</tt> subdirectories, run 

$ gmshFoam . . -decomposedMesh

. Beware that with this gmshFoam only imports all the decomposed meshes together and no topological merging (merging points/faces on processor boundaries) is performed.

5.6 Postprocessing a case

Suppose you are in a case directory of a finished run. To read in all the field data simply read <tt>system/controlDict</tt>. 

$ gmsh system/controlDict

To do it similarly with <tt>gmshFoam</tt>, run 

$ gmshFoam . .

If you only need the latest timestep, run 

$ gmsh -string "PostProcessing.FoamStartTime=\"latestTime\";" system/controlDict
.

5.7 Superposing a mesh and postprocessing views

Obviously you can also superpose a mesh and postprocessing views by running 

$ gmsh ..foam system/controlDict

under a case directory. This is sometimes useful when debugging a case, e. g. tracking down a computation error resulting from bad mesh quality.

5.8 Watching a running case

Suppose you are in a running case directory. To watch the latest field data on-the-fly run 

$ gmshFoam . . -monitor

and hit "OpenFOAM case monitor," select watching interval, and hit "Start."

5.8.1 Example gmshFoamMonitorDict

<tt>GmshFoamMonitor</tt> (case watcher) usually works without dictionary. In that case <tt>stopAt</tt> will be set to "<tt>endTime</tt>" and other options will be set to empty strings. You will find the settings sufficient for most cases. However, in case you would like to tweak, write <tt>gmshFoamMonitorDict</tt> as follows and place it under <tt>system</tt> subdirectory. 

FoamFile
{
    version         2.0;
    format          ascii;

    root            "";
    case            "";
    instance        "system";
    local           "";

    class           dictionary;
    object          gmshFoamMonitorDict;
}

// The time where monitoring finishes; "endTime" if
// monitors up to exactly the endTime set in controlDict.
stopAt "0.5";

// Initial options given before displaying the first views (for setting the
// viewing angles etc). Don't forget the last semicolon (";").
initialViewOptions "General.Trackball=0;\
    General.RotationX=10;General.RotationY=-15;General.RotationZ=0;";

// Options applied each time new time views are created (for setting
//  the clipping planes etc). Again, don't forget the last semicolon (";").
viewOptions "View.Axes=3;\
    General.Clip0=4;General.Clip0A=0;General.Clip0C=-1;General.Clip0D=0.005;\
    General.Clip1=16;General.Clip1A=0;General.Clip1C=1;General.Clip1D=-0.005;";

6 Technical

6.1 General

  • GmshFoam has not been so well tested. It should be considered as a permanent pre-alpha, so any feedback is welcome at this thread of the Message Board.
The internal overall structure of gmshFoam
  • GmshFoam is internally structured as shown in the figure. The direct importer/exporter and the standalone converters share most of the conversion code in libgmshFoam. libgmshMessageStream is a mechanism to share text message output with verbosity control and capability to redirect the messages to Gmsh text message console when used as the importer/exporter.

6.2 Mesh exporter / gmsh2ToFoam

  • The direct mesh exporter uses an internal information of Gmsh to determine if physical regions are defined, so the exporter should correctly detect the physical region definitions even if they are labeled as all zero.
  • Currently the direct mesh exporter have no option that corresponds to <tt>-noAutoInvert</tt> in <tt>gmsh2ToFoam</tt> (i. e. <tt>autoInvert</tt> is always enabled). The direct exporter have no <tt>checkMesh</tt> capability either, since I could not find a way to redirect the output messages of the checker in OpenFOAM library to the Gmsh message console.

6.3 Field data importer / foamToGmsh

  • The field data importer and <tt>foamToGmsh</tt> supports all the combinations of vol/surface/point-Scalar/Vector/symmTensor/Tensor fields.
  • Polyhedral cells (cell shapes other than tets/hexes/pyrs/prisms)/polygon faces (other than tris/quads) are not supported. Maybe a kind of polyhedral/polygon decomposer should be implemented following the one implemented in <tt>foamToVTK</tt> but currently I have no human power to do it.
  • Since Gmsh does not seem to have direct handling capability of mesh motions, it is implemented by way of the GeneralizedRaise feature. When the importer detects a mesh motion (the presence of <tt>polyMesh/points</tt> in a time directory), it creates extra vector field views called <tt>vol</tt>/<tt>surface</tt>-<tt>MeshMotion</tt>s, depending on what type of meshes it has to handle, representing mesh point displacements from the initial mesh. Then the importer automatically links the GeneralizedRaise targets of vol/surface field views to the corresponding <tt>MeshMotion</tt> views. Similar things apply to views converted by <tt>foamToGmsh</tt>; <tt>foamToGmsh</tt> also writes out the <tt>MeshMotion</tt> views when it detects a mesh motion. The difference is that you have to manually link the views by checking Tools -> Options -> View -> Offset -> "Use general transformation expressions" and selecting the corresponding <tt>MeshMotion</tt> view as "Data source," because the converted views have no information about what mesh type and what type of information the views have. I'd be grateful if anyone lets me know a better way of handling mesh motions.
  • Mesh motion is supported only for point motions, but not for topological changes.
  • Lagrangian particles are not supported (I'd like to realize it, but no idea as to implementation).

6.4 Mesh importer / foamMeshToGmsh

  • Mesh with polyhedral cells/polygon faces are not supported.

6.5 gmshFoamMonitor

  • Potentially you'd be able to do so many things with <tt>gmshFoamMonitor</tt> by proper programming. Definitely the case directory monitoring is not all it could do - I made it to do so just because it was the simplest idea to realize. Technically you can embed your solver code itself to <tt>gmshFoamMonitor</tt> and establish more dense communication between Gmsh and <tt>gmshFoamMonitor</tt>. Its source code contains only about 200 lines, so customizing should be fairly easy. It is left to you to make the capability more interesting and usable.

7 Download

The current version:

  • There is no released version for now.

Tutorial:

Past versions (will NOT work with OpenFOAM 1.5 or later):

8 Feedback

The forum thread for feedback is here. The author will not respond to problems coming from using the past versions.

9 History

7islands 07:27, 27 Oct 2007 (CEST) (Takuya Oshima):

  • Documentation update.

7islands 16:00, 5 Sep 2007 (CEST):

  • Field importer/foamToGmsh supports symmTensor and pointMesh.
  • Introduced decomposed mesh viewing mode through polyMesh importer.
  • Introduced exception handling.
  • Introduced compatibility mechanism across different versions of OpenFOAM with OF 1.4.1 support.
  • autoInvert set to on by default in gmsh2ToFoam/mesh exporter.
  • Other improvements.

7islands 09:55, 2 Aug 2007 (CEST):

  • gmshFoam is now based on the 2.0.8 version of Gmsh. This migration involves removal of the following codes from the patch since they have been contributed to the official 2.0.8 release of Gmsh:
    • step back/forward buttons
    • extension to Streamlines plugin to draw streamlines over unsteady multistep field view
    • Cygwin-specific fix in meshGRegionTransFinite.cpp
  • Removed the <tt>Mesh.FoamRemoveUnusedPoints</tt> option since the 2.0.8 release has its own unused point remover.
  • Added direct mesh importer and foamMeshToGmsh (experimental).
  • Several bugfixes and improvements.

7islands 03:30, 16 May 2007 (CEST):

  • Case monitoring now works under Cygwin.
  • gmshFoam is accessible from FoamX.
  • foamToGmsh writes view files in binary format.
  • Added "step forward" and "step backward" buttons at the bottom of the Gmsh graphics window.
  • Minor bugfixes and small improvements.

7islands 12:43, 11 Apr 2007 (CEST):

  • Initial upload.

Retrieved from "https://openfoamwiki.net/index.php?title=Contrib_gmshFoam&oldid=17168"
  • GNU Free Documentation License 1.3
  • Powered by MediaWiki
  • Powered by Semantic MediaWiki