Contrib gmshFoam

From OpenFOAMWiki
Revision as of 06:01, 13 April 2007 by 7islands (Talk | contribs)

(The documentation work is still underway - more to come in the following days!)

Valid versions: OF version 13.png OF version 14.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.

Maybe you know what pre/postprocessings are, but what about midprocessing? As a proof-of-concept implementation, the current version has a simple on-the-fly visualization capability, i. e. watches the case directory of an ongoing computation and visualizes the newest field data automatically as soon as they are written into the directory.

2 Words of warning

A quotation from the Gmsh Reference Manual: Gmsh was designed to solve academic "test cases", not industrial-size problems. You may find that Gmsh is too slow for large problems (with thousands of geometric primitives, or millions of mesh/post-processing elements). This also applies as-is to gmshFoam. Besides, there are lots of technical footnotes, remarks and asterisks. See the Technical section below.

3 Installation

3.1 Prerequisites

  • The gmshFoam-20070411 package: Download from the Download section below.
  • gmsh-2.0.7-source.tgz: You need the source distribution of Gmsh.
  • The autoconf utility that comes with your linux distribution.

3.2 Installation procedure

[Note for OpenFOAM 1.4 users: in the following explanations the strings "1.3" and "linuxAMD64" should be replaced with "1.4" and "linux64."]

In the following procedure, as an example the home directory is assumed to be the author's own home directory:

  • The home directory: /home/ohshima

The gmshFoam and Gmsh packages are assumed to be downloaded into:

  • The gmshFoam package: /home/ohshima/OpenFOAM/ohshima-1.3/applications/utilities
  • The Gmsh source package: /home/ohshima/OpenFOAM/linuxAMD64


1. Setup the OpenFOAM environment.
$ source ~/OpenFOAM/OpenFOAM-1.3/.OpenFOAM-1.3/bashrc
2. Build the libraries and standalone utilities.
$ cd ~/OpenFOAM/ohshima-1.3/applications/utilities
$ tar -zxf gmshFoam-20070411.tar.gz
$ cd gmshFoam-20070411
$ ./Allwmake

With this step the followings will be installed:

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

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

$ cd ~/OpenFOAM/linuxAMD64
$ tar -zxf gmsh-2.0.7-source.tgz
$ mv gmsh-2.0.7 gmsh-2.0.7-src
$ cd gmsh-2.0.7-src
$ patch -p1 < ~/OpenFOAM/ohshima-1.3/applications/utilities/gmshFoam-20070411/gmsh-2.0.7-foam-20070410.diff
$ autoconf
$ ./configure --prefix=/home/ohshima/OpenFOAM/linuxAMD64/gmsh-2.0.7 \
  --with-foam-prefix=/home/ohshima/OpenFOAM/ohshima-1.3/applications/utilities/gmshFoam-20070411
...
checking for main in -lhdf5... no
checking for main in -lgmshMessageStream... yes    <<--- This line shows 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.7-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 ~/OpenFOAM/linuxAMD64/gmsh-2.0.7/bin.

4. Add the path to Gmsh in one of the setup scripts. For example add the following line to the last of ~/OpenFOAM/OpenFOAM-1.3/.bashrc.

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

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 optional extension ".foam" will be removed).
  • 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.FoamRemoveUnusedPoints: Remove unused points (the centers of circular arcs etc.) from the converted OpenFOAM mesh? (1 = yes (default), 0 = no)
  • 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).

4.2 gmshFoam

gmshFoam <root> <case> [-monitor or <.geo file>]
How to start a case monitoring

GmshFoam has three modes depending on the arguments specified:

  • 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 save the mesh into the constant subdirectory.
  • 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 -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 and visualize the newest field data with the interval specified in the launcher dialog.

4.3 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 gmshFoamMonitorDict in the system subdirectory every time new data is 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, see the example gmshFoamMonitorDict included under the example directory of the gmshFoam package.

4.4 gmsh2ToFoam

Gmsh2ToFoam is the standalone version of the direct mesh exporter in Gmsh and works without Gmsh. The gmsh2ToFoam that comes with this package has all the features of the original gmsh2ToFoam, plus

  • a simplified checkMesh test: turned on by default. Use -noCheckMesh to turn off.
  • automatic launching of Gmsh: automatically launches Gmsh with "gmsh -3" when a file with the .geo extension is specified; then converts the produced .msh file to the OpenFOAM format.
  • verbosity control: verbosity can be controlled by -verbosity <verbosity> where <verbosity> is a number from 0 to 5 (the default is 3, along with the default setting of the Gmsh General.Verbosity variable).
  • a faceZone naming bugfix.

For other features, see the original gmsh2ToFoam page.

4.5 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 file format of ASCII type. 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>.

5 Technical

5.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.
  • Beware of sudden crash of Gmsh - as you know the OpenFOAM libraries gmshFoam depends on are basically programmed to issue a fatal error when it encounters a problem. This is not so much of a problem, or rather a preferable behavior for usual solvers and utilities, but it means a sudden crash for a GUI application. Maybe I should implement a signal catcher or something, I don't know if it's possible however.

5.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>-autoInvert</tt> in <tt>gmsh2ToFoam</tt> since so far I have never encountered the inversion problem in recent versions of Gmsh. 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.

5.3 Field data importer / foamToGmsh

  • The field data importer and <tt>foamToGmsh</tt> supports all the combinations of vol/surface-Scalar/Vector/Tensor fields. Currently pointFields are not supported.
  • 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.

5.4 gmshFoamMonitor

  • Potentially you can 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.

6 Download

gmshFoam-20070411.tar.gz: The gmshFoam package

You also need to download <tt>gmsh-2.0.7-source.tgz</tt> from the Gmsh website.

7 History

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

  • Initial upload.