Difference between revisions of "Contrib Parallelized Native OpenFOAM Reader for ParaView"

From OpenFOAMWiki
m (Features)
(Downloads)
 
(43 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The OpenFOAM reader included in ParaView3 (tips for enabling the reader is documented [[Tip_Build_A_Paraview3_Plugin|here]]) lacks a number of essential features to be practially used, so I re-coded the reader from ground up and posted to [http://openfoam.cfd-online.com/cgi-bin/forum/show.cgi?tpc=1&post=17466#POST17466 the Message Board]. This page is meant as the documentation for the reader.
+
=Short description=
 +
 
 +
This is an OpenFOAM native reader for ParaView 3.10-3.14 series, VTK, Salome ParaViS module and its parallelization extension for <tt>decomposePar</tt>-ed cases.
  
 
=Features=
 
=Features=
 +
* Fast. For a rough performance indication, the reader loads an ascii-gzipped mesh with 3.5 million hexahedral cells in 9 seconds on the developer's 3.0 GHz Mac Pro.
 +
* Memory efficient. The readers typically requires less memory than PV3FoamReader. The above mentioned case crashes a 32-bit version of ParaView due to out of memory if loaded by PV3FoamReader, while the reader does not.
 +
* Portable. The reader works under Linux, Mac OS X and Windows without any porting works.
 +
* Supports multi-region cases and parallel reading of decomposed cases.
  
The reader
+
=License=
* supports the ParaView 3.3 CVS development version (as of Mar. 24, 2008) and the 3.2.1 released version.
+
The software is licensed under the ParaView License 1.2.
  
* is tested under Linux x86, x86_64, VS2003.net/2008 on Windows and Mac OS X Leopard (10.5).
+
=Installation=
 +
The reader can be installed as either plugins or a builtin reader.
 +
*If one chooses to install the reader as plugins the main ParaView sources does not have to be modified. Thus in general installing as plugins is recommended.
 +
*Installing as a builtin reader is meant for Linux package maintainers who intend to distribute their own versions of ParaView sources and binaries.
  
* has improved performance and compatibility over the reader included in the ParaView sources.
+
==Prerequisites==
 +
* CMake 2.6 or later is required.
 +
* The reader has absolutely no dependence on any of the OpenFOAM libraries (which is why the reader is called native). However the reader can be installed somewhat easier as plugins if installed with ParaView that comes with the ThirdParty package of OpenFOAM as shown below.
 +
* When configuring the reader with CMake, a system POSIX regex (regular expression) library is searched for and the reader uses the library if found in order to support regex'ed dictionary keyword syntax. If one is not found but the reader is built with Visual Studio 2008 SP1 or later, the regex library in STL TR1 extension that comes with Visual Studio 2008 SP1 or later is used instead. If none were found, the regex library included in VTK is used as the final fallback option. This is because at least a pattern in the extended regular expression (ERE) is known not supported by the VTK regex library. Hence on Windows, building the reader with Visual Studio 2008 SP1 or later is strongly recommended.
  
* supports all combinations of vol/point/lagrangian (of class Cloud)-Scalar/Vector/SphericalTensor/SymmTensor/Tensor fields (See Notes below to use the lagrangian feature).
+
==Install as plugins (Linux and OS X)==
 +
===Building and installing ParaView with parallelization support===
 +
If you only want to read decomposed cases in serial, the reader works without parallelization support of the main ParaView build. However you would naturally want to turn it on for making full use of the capability of the reader. In order for ParaView to work in parallel, one has to do a full build, installation and setup of ParaView. See
 +
http://paraview.org/Wiki/ParaView:Build_And_Install
 +
http://paraview.org/Wiki/Starting_the_server
 +
for full instructions. When configuring with CMake, at least the following variables should be set:
 +
BUILD_SHARED_LIBS = ON
 +
CMAKE_BUILD_TYPE = Release
 +
PARAVIEW_USE_MPI = ON
 +
. After installation, do not remove the ParaView build directory but keep it since it is required in building the plugins afterwards.
  
* supports compressed(gzipped)/uncompressed-ascii/double precision binary data formats. Single precision binary format is not supported.
+
Alternatively, a parallelized ParaView can be built using the OpenFOAM ThirdParty source package by issuing the following commands under OpenFOAM environment:
 +
<bash>cd $WM_THIRD_PARTY_DIR
 +
./makeParaView -mpi
 +
</bash>
  
* has a builtin cell data to point data filter (not as accurate as the volPoint interpolator in paraFoam but supposed to be better than the one in ParaView, see Notes below)
+
===Building and installing the plugins===
 +
Create a build directory for the plugins and point CMake from the build directory to the top directory of the reader source tree (the directory where the <tt>README</tt> file is in).
 +
<bash>mkdir <the plugin build directory>
 +
cd <the plugin build directory>
 +
ccmake <the top directory of the reader source tree>
 +
</bash>
  
* has a neat user interface. Patch and array selection lists are now offered.
+
Then set
 +
CMAKE_BUILD_TYPE = Release
 +
CMAKE_INSTALL_PREFIX = <one of the local plugin directories of the ParaView installation>
 +
CMAKE_OSX_ARCHITECTURES = <the value used for the main ParaView build>
 +
ParaView_DIR = <the directory where ParaView was built>
 +
where <tt>CMAKE_OSX_ARCHITECTURES</tt> is only required under OS X. If one is unsure about where to install the plugins, the plugin directories can be checked by launching ParaView and choosing the ''Tools -> Manage Plugins/Extensions...'' menu. There one will see "''Local plugins are automatically searched for in...''" followed by a list of directories. Alternatively, if the plugins are being built within OpenFOAM environment in conjunction with the ThirdParty ParaView, all of these variables are set automatically as default values.
  
* supports some (but not all) of the extended file format introduced in OF 1.5.
+
Then build and install the plugins.
 +
<bash>make
 +
make install
 +
</bash>
  
=Installation=
+
By these steps the reader and the UI plugins will be installed to the local plugin directory.
  
1. Get the ParaView3 source.
+
'''[!!IMPORTANT!!]''' ParaView may have different remote plugin directories than the local plugin directories when in client/server mode. In such cases the installed server-side plugin under the local plugin directory must be manually copied (or symbolic linked) by hand to one of the remote plugin directories. To check remote plugin directories, start ParaView in client/server configuration and choose ''Tools -> Manage Plugins/Extensions...'' . Attempting to read OpenFOAM cases in client/server mode without the plugin loaded as a remote plugin '''will''' crash ParaView.
*For 3.3-CVS:
+
<bash>cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 login
+
    (respond with empty password)
+
cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 co ParaView3</bash>
+
*For 3.2.1:
+
<bash>tar -zxf paraview-3.2.1.tar.gz
+
ln -s ParaView3.2.1 ParaView3</bash> (a symbolic link is required for the reader package to be correctly unpacked)
+
  
2. Untar the package at the parent directory of ParaView3 source tree
+
==Install as plugins (Windows)==
(the directory where you issued the above cvs commands). This will
+
The overall installation steps are identical to those for Linux and OS X except that one would probably use <tt>cmake-gui</tt> instead of <tt>ccmake</tt> and Visual Studio IDE (open <tt>Project.sln</tt> under the plugin build directory, set Configuration to <tt>Release</tt> and build <tt>ALL_BUILD</tt> followed by <tt>INSTALL</tt>) instead of <tt>make</tt>. The reader has been only tested with Visual Studio, and as written in the Prerequisites section, Visual Studio 2008 SP1 or later is strongly recommended. Building under MinGW has not been tested.
overwrite the reader code included in the source tree.
+
<bash>tar jxf vtkOpenFOAMReader-YYYYMMDD.tar.bz2</bash>
+
3. Patch the XML code at the parent dirctory.
+
<bash>patch -b -p0 < readers.xml.diff</bash>
+
*For 3.2.1: add the following piece into ParaView3.2.1/Qt/Components/Resources/XML/ParaViewReaders.xml.
+
<xml><Reader name="OpenFOAMReader"
+
          extensions="foam"
+
          file_description="OpenFOAM Files">
+
</Reader></xml>
+
4. Build ParaView3 as usual. It is highly recommended to turn on
+
compiler optimization (by setting CMAKE_BUILD_TYPE to Release) since the reader is dead slow
+
without optimization. If you get a bit better performance than
+
paraFoam the optimization is working adequately.
+
  
=Notes=
+
[Tip] One might want to [http://www.paraview.org/pipermail/paraview/2009-March/011500.html take care about the manifest file of the Visual Studio 2008 SP1 runtime DLLs] if the binary is intended to be deployed without requiring to install redistributable runtime DLLs separately.
  
* To load an OpenFOAM case, you either have to
+
==Install as a builtin reader==
** create an empty stub file <caseName>.foam right under the case directory, where <caseName> is an arbitrary string other than  the strings that starts with "controlDict," or
+
Follow the "Install by patching the ParaView sources" section of <tt>INSTALL.special</tt> in the source package. After that, build ParaView as usual.
** create a symbolic link from controlDict to controlDict.foam and open controlDict.foam.
+
  
* The builtin cell-to-point filter works like a Cell Data to Point Data filter in ParaView in that it just takes the average of cell values connected to a point. The difference is that the builtin filter takes boundary patch values into account. The filter is not as accurate as the volPoint interpolator in paraFoam, which further does inverse distance weighting of cell values.
+
==Install as plugins for Salome ParaViS module==
 +
Follow <tt>INSTALL.special</tt> in the source package.
  
* The cell-to-point filter is computationally demanding so you can turn it off by deselecting "Create cell-to-point filtered data" on the reader panel.
+
=Usage=
 +
In order to open OpenFOAM case, either
 +
* open <tt>system/controlDict</tt> (which only works for the development version), or
 +
* create an empty stub file <tt><caseName>.foam</tt> right under the case directory, where <tt><caseName></tt> is an arbitrary string other than those that starts with "<tt>controlDict</tt>," and open <tt><caseName>.foam</tt>
  
* Several compile-time performance-related configuration options are now provided at the beginning of vtkOpenFOAMReader.cxx. With defaults the reader
+
There is also a script for user convenience that works like <tt>paraFoam</tt>, called <tt>pf</tt>. The script creates the stub file and launches ParaView in background. For available options, run
** omits CRC checks for gzipped files (except on Windows)
+
<bash>pf -help
** counts line numbers where the FoamFile parser is reading (if turned off, the line number will always be shown as 0 when the reader issues a parser error in return for a bit of additional performance)
+
</bash>
** uses its own string to floating point conversion routine, which is fast but may be a bit inaccurate than the system strtod().
+
in terminal.
  
* To separate Eulerians and Lagrangians, extract Node 0 for Eulerians and Dataset 1 right under Root with Filter->Extract Block (ParaView 3.3) or group 0 for Eulerians and group 1 for Lagrangians with Extract Group (ParaView 3.2.1).
+
For general operations of the reader, see [http://sourceforge.net/projects/of-interfaces/files/vtkPOpenFOAMReader/vtkPOpenFOAMReader-r173-20090920/readerPanel.pdf/download <tt>readerPanel.pdf</tt>].
  
* To create a slice with volField data you have to extract internal mesh (dataset 0) or turn off reading patches in the reader panel.
+
=Notes (general)=
 +
# Dictionary syntax <tt>~OpenFOAM</tt> expands only to <tt>$HOME/.OpenFOAM</tt> where <tt>$HOME</tt> is the home directory of the user.
 +
# The <tt>#remove</tt> dictionary directive is not supported.
 +
# The builtin cell-to-point filter works like a Cell Data to Point Data filter in ParaView in that it just takes the average of cell values connected to a point. The difference is that the builtin filter takes boundary patch values into account. The filter is faster but less accurate than the volPoint interpolator in <tt>paraFoam</tt>, which further does inverse distance weighting of cell values. The cell-to-point filter is still computationally demanding thus can be turned off by unchecking "''Create cell-to-point filtered data''" on the reader panel.
 +
# In order to create slices with volField data one may have to extract internal mesh or turn off reading patches in the reader panel before running the Slice filter, otherwise the sliced data may be garbled.
 +
# When the ''List timesteps according to controlDict'' checkbox is turned on, the reader lists time instances according to descriptions in <tt>controlDict</tt> when (<tt>adjustTimeStep</tt>, <tt>writeControl</tt>) == (<tt>yes</tt>, <tt>adjustableRunTime</tt>) or (<tt>no</tt>, <tt>timeStep</tt>) (i. e. writing interval is supposed to be constant in simulated time), or otherwise, lists all valid time directories.
 +
# The reader lists field names according to the "<tt>object</tt>" entry in <tt>FoamFile</tt> header, whereas <tt>paraFoam</tt> lists according to the file name of the object. Hence a valid <tt>FoamFile</tt> header is required for every object.
 +
# Reading cellZones for polyhedral mesh with the Read Zones feature may cause ParaView to thrash.
 +
# The reader only takes the "<tt>value</tt>" and "<tt>uniformValue</tt>" entries into account for boundary fields. If none of the entries exists, the corresponding patch-internal field values are used (i. e. equivalent to <tt>zeroGradient</tt> b. c.).
 +
# When watching running case, one may occasionally see reader errors due to race conditions where the reader reads up until the end of file while the file is being written. Although the developer has put much effort in avoiding crashes in such cases, there may still be ones. Doing important tasks while watching case is thus not recommended.
 +
# Multi-region case is detected by existence of mesh files under subdirectories found in first two time directories. If a case is determined to be a multi-region case, the selection of <tt>internalMesh</tt> of the default region in the reader panel is turned off by default.
 +
# The variable expansion follows the original OpenFOAM 1.6 behavior in that variables match regex'ed keywords, whereas they do not in 1.6.x or later.
  
* The reader lists time instances according to descriptions in controlDict when (adjustTimeStep, writeControl) == (yes, adjustableRunTime) or (no, timeStep) (i. e. writing interval is supposed to be constant in simulated time), or otherwise, lists all valid time directories. This is a different behavior from paraFoam which always lists all valid time directories in a case directory.
+
=Notes (Parallel-specific)=
 +
# The ''Case Type'' selection combo box determines whether the case to be read is a reconstructed case (a serial case) or a decomposed case (a case decomposed into <tt>processor<i>X</i>/</tt> subdirectories). The reader can read decomposed cases even when ParaView is run in builtin server (serial) mode. If ParaView is running in client/server mode and the servers (<tt>pvserver</tt>s) are running in parallel, the decomposed mesh regions are read in parallel.
 +
# The number of decomposed mesh regions and the number of <tt>pvserver</tt> processes do not have to be identical, with a known exception of the note 6 below. Processor subdirectories are detected by server process 0, and each <tt>processor<i>X</i>/</tt> subdirectory is assigned to a server process in an interleaved way. For example, if one has 5 processor subdirectories and running 2 <tt>pvserver</tt>s, the <tt>pvserver</tt> process 0 reads <tt>processor0/</tt>, <tt>processor2/</tt> and <tt>processor4/</tt> subdirectories while <tt>pvserver</tt> process 1 reads <tt>procssor1/</tt> and <tt>processor3/</tt> subdirectories. Which process owns which decomposed regions can be checked by ''Filters -> Process Id Scalars''.
 +
# Timesteps are taken from a first processor subdirectory (typically <tt>processor0/</tt>) by server process 0 and broadcasted to other processes.
 +
# In client/server mode, reconstructed case is loaded by <tt>pvserver</tt> process 0. ''Merge Blocks -> D3'' can be used in order to distribute the data. NB: ''Merge Blocks'' is still required nevertheless ParaView 3.6.1 and on ''D3'' can be applied to multiblock data, due to an incompatibility with ''D3'' of the reader which causes ''D3'' to deadlock. The developer is working on resolving the issue.
 +
# The reader does nothing about adding ghost cells. Hence one has to see processor boundaries when the geometry is represented in ''Wireframe'' or ''Surface''. This could be especially problematic if one wants to extract surfaces. In order to remove internal processor boundaries from the output of the ''Extract Surface'' filter, run ''Merge Blocks -> D3 -> Extract Surface''. Similarly, when the reader is run in serial or in builtin mode, the ''Clean to Grid'' filter can be used in order to remove internal processor boundaries.
 +
# Beware that Stream Tracer may crash <tt>pvserver</tt>s if more <tt>pvserver</tt>s are run than the number of decompsed regions. The cause of the problem has not been tracked down yet, but so far the developer is regarding it is not in the reader but in ParaView because the crash can be reproduced with another reader as well. The problem was reported as [http://paraview.org/Bug/view.php?id=9787 bug #9787].
 +
# The reader does not output processor boundary patches of decomposed regions. In order to see the processor patches, each <tt>processor<i>X</i>/</tt> subdirectory has to be opened as a separate case.
  
* The reader lists array names according to the "object" entry in FoamFile header, whereas paraFoam lists according to the file name of the object. So you need a valid FoamFile header for every object.
+
=Miscellaneous=
  
* The Accumulate Patches checkbox in the reader panel is meant to be used for topo change cases to append patches that don't exist in the initial timestep into the selection list over an animation run. To update the patch selection list after the run, deselect controlDict.foam in Pipeline Browser once and re-select it.
+
* The parallel extension part is quite a straightforward implementation of what are written in the Section 21.3 of The ParaView Guide.
  
* Handling of boundary conditions is quite poor as of now; if a boundary patch doesn't have a value entry the corresponding patch-internal field value is used (i. e. equivalent to zeroGradient b. c.)
+
* In my testing I get typically 2.3x - 2.5x speedups in mesh loading time by 4 process parallel execution. However everything is not so rosy especially in that I often get slower rendering times by parallel executions. As no one but the developer being quite new to parallel visualization, the developer is interested in your findings. You are welcomed to post them to the forum.
  
* Mesh which consists of polyMesh/points, polyMesh/faces and polyMesh/cells (old mesh format) is not supported.
+
* The reader that comes with the Git head of ParaView 3.9 has experimental support for native polyhedron ([http://www.vtk.org/doc/nightly/html/classvtkPolyhedron.html vtkPolyhedron]). The implementation in the reader, which the developer contributed, is experimental because <tt>vtkPolyhedron</tt> itself is still experimental. The reader has supported the development of the new cell type since its early stage by helping providing polyhedral test cases. Just uncheck "''Decompose Polyhedra''" in the reader panel in order to try out the cell type.
  
*On 3.3-CVS Filters->Append Attributes and Filters->Append Datasets can be run after running Filter->Merge Blocks over the reader output. Filters->Surface Flow runs as is since it is now compatible with the reader output. However the calculated value of Surface Flow should be taken only as a rough indication. Using calcMassFlow ([[Contrib_calcMassFlow|here]] or [http://openfoam.cfd-online.com/cgi-bin/forum/show.cgi?tpc=1&post=20736#POST20736 here]) is recommended for accuracy. The technique does not work for 3.2.1 because there is no Merge Blocks filter.
+
=Downloads=
 +
[https://github.com/7islands/vtkPOFFReader Development version] at GitHub:
 +
* The developer had given up the idea of creating a stable release for the moment since the reader project has to follow both ParaView and OpenFOAM developments, both of which are considered very active (the moving targets). NB: There can always be bugs, errors, crashes or even incomplete codes (the developer sometimes commits works in progress for backup purpose).
  
* For binary-formatted Lagrangian positions files the reader only supports the ones created by OF version 1.4 or later.
+
Downloads from other sources:
 +
*Contributed Linux/OS X ParaView packages with the reader included (the versions of the reader may not be up-to-date): [http://bugs.gentoo.org/243362 Gentoo], [https://launchpad.net/~cae-team/+archive/ppa Ubuntu 10.04], [https://sourceforge.net/apps/mediawiki/centfoam/index.php?title=Main_Page CentOS 5.x x86_64]
 +
*Ubuntu 10.10 seems to have ParaView 3.8.1 with parallelization/Python scripting enabled in its packages (<tt>sudo apt-get install paraview</tt>).
 +
*Official releases of [http://paraview.org/paraview/resources/software.html ParaView] and [http://www.vtk.org/VTK/resources/software.html VTK] from Kitware: A version of the reader is a part of the official Kitware releases of ParaView and VTK. The version is based on a previous release of vtkPOpenFOAMReader-r64-20081005 since the developer had to do some specific works of addressing compilation issues in some older compilers. The most notable limitations of the version are
 +
** The version supports dictionary syntaxes up to OpenFOAM 1.5 (no support for regular expressions).
 +
** The reader does not have the custom Qt UI (the Reload and Watch buttons) since the developer used a GPLed version of Qt 4.3 at that time.
  
* The FoamFile parser is still under development so if you find a bug posting a minimal test case will be highly appreciated.
+
Technical documentation:
 +
* [http://of-interfaces.sourceforge.net/OS-CAE1-2-open-e.pdf A presentation about technical aspects of the reader (PDF 1,200 KBytes)]
  
=Downloads=
+
Past versions:
Download from [http://openfoam.cfd-online.com/cgi-bin/forum/show.cgi?tpc=1&post=17466#POST17466 the native reader thread] on the Message Board.
+
*Parallel reader development snapshot: [[Media:vtkPOpenFOAMReader-20080831.tar.gz|vtkPOpenFOAMReader-20080831.tar.gz]]
 +
*Ancient serial versions: Download from [http://openfoam.cfd-online.com/cgi-bin/forum/show.cgi?tpc=1&post=17466#POST17466 the native reader thread] on the Message Board.
  
You can also download prebuilt binaries with the reader included [http://oshima.eng.niigata-u.ac.jp/OpenFOAM/ParaView/ here] (currently only available for Windows).
+
=Feedbacks=
 +
* A use case on a supercomputing cluster: [http://www.csc.fi/csc/kurssit/arkisto/ofud09 "Parallelized OpenFOAM reader for Paraview - An example"] by CSC Finland
 +
* [http://serverlab.unab.edu.co:8080/wikimedia/memorias/shortspapers.html "Construcción de un túnel de viento virtual sobre AccessGrid y ParaView"] (Construction of a virtual wind tunnel on AccessGrid and ParaView) by Camilo Cortés et al (in Spanish). One comment is that the bad parallel scaling of ParaView as shown in Tabla 1 is expected, because [http://www.vtk.org/doc/release/5.2/html/a00337.html the Stream Tracer is essentially a serial algorithm thus only one process is active at one time]. Nonetheless the developer appreciates the fair citation.
 +
* A YouTube video [http://www.youtube.com/watch?v=azc2gHbp4tk ParaView with OpenFoam demo] by a guy in Columbia, who seems to be demonstrating the reader working in client/server mode.
 +
* [http://github.com/themiwi/ParaView3POpenFOAMReader A GitHub mirror of the repository] by Michael Wild, which is not affiliated with the developer.
 +
* [http://joomla.bluecape.com.pt/index.php?option=com_content&task=view&id=18&Itemid=30&lang=en#blueCFD blueCFD] ([[Tip_Cross_Compiling_OpenFOAM_in_Linux_For_Windows_with_MinGW|a MinGW/MinGW64 porting]] of OpenFOAM) by blueCAPE Lda. includes the reader with their own build of ParaView.
 +
 
 +
If you found bugs or have comments, post to [http://openfoam.cfd-online.com/cgi-bin/forum/show.cgi?tpc=1&post=17466 the native reader thread].
  
 
=History=
 
=History=
 +
[[User:7islands|7islands]] 09:55, 20 September 2009 (UTC) (Takuya OSHIMA): Released 20090920. Changes from the 20081005 version are
 +
* Added support for extended dictionary syntaxes of OpenFOAM 1.6, notably the regex'ed dictionary keywords.
 +
* The reader now compiles with a drastically wider range of compilers. The tested compilers include many GCC versions from 3.3.2 to 4.4.1 (including Apple's compilers under 64bit mode), Intel Compiler 11/11.1, Sun Studio 12/12.1, Open64 4.2.1/4.2.2, Visual Studio 2003.net/2008SP1.
 +
* Added "watching a running case" functionality (which in fact has long been implemented in the svn-versions).
 +
* Better detection and handling of multi region cases. The reader now can read <tt>chtMultiRegionFoam/multiRegionHeater</tt> case. Note that one will still get an error about missing "<tt>uniform</tt>" keywords in <tt>buoyantPressure</tt> BC sections of the field files when reading the case as is. In order to eliminate the error, either add the uniform keyword to or remove entirely the value entries of the <tt>buoyantPressure</tt> sections of the field files and <tt>cahgeDictionaryDict</tt>s under the <tt>system</tt> subdirectory.
 +
* Added support for single precision binary format.
 +
* Improved performance in reading files in double precision binary format.
 +
* Improved installation steps.
 +
* Rewritten pvFoam script.
 +
* Changed the license of some more files to the BSDL.
 +
* Workaround for a locale problem in string-to-floating conversion under Qt 4.5/Linux.
 +
* Fixed many bugs, including crashes (thanks to all the reporters).
 +
* Other features that I don't remember.
 +
 +
[[User:7islands|7islands]] 06:10, 23 March 2009 (CET) (Takuya OSHIMA): Added a win32 binary package release.
 +
 +
[[User:7islands|7islands]] 06:13, 5 October 2008 (CEST) (Takuya OSHIMA): Released 20081005. Notable changes from the 20080831 snapshot are
 +
* Unified application interfaces of the serial/parallel readers. Both can be accessed by opening a .foam file. Subsequently, readers.xml no longer have to be patched -- which makes tracking the CVS head of ParaView easier.
 +
* Fixed several bugs, notably deadlocks.
 +
* Added lagrangian labelField support, casePath addition to output.
 +
* Added feature to change case without reinstanciating another reader.
 +
 +
[[User:7islands|7islands]] 06:57, 31 August 2008 (CEST) (Takuya OSHIMA): moved to Contrib section. Initial upload of the parallelized version.
 +
 
[[User:7islands|7islands]] 02:58, 28 April 2008 (CEST) (Takuya OSHIMA): update for the 20080324 version.
 
[[User:7islands|7islands]] 02:58, 28 April 2008 (CEST) (Takuya OSHIMA): update for the 20080324 version.
  

Latest revision as of 15:21, 7 August 2014

1 Short description

This is an OpenFOAM native reader for ParaView 3.10-3.14 series, VTK, Salome ParaViS module and its parallelization extension for decomposePar-ed cases.

2 Features

  • Fast. For a rough performance indication, the reader loads an ascii-gzipped mesh with 3.5 million hexahedral cells in 9 seconds on the developer's 3.0 GHz Mac Pro.
  • Memory efficient. The readers typically requires less memory than PV3FoamReader. The above mentioned case crashes a 32-bit version of ParaView due to out of memory if loaded by PV3FoamReader, while the reader does not.
  • Portable. The reader works under Linux, Mac OS X and Windows without any porting works.
  • Supports multi-region cases and parallel reading of decomposed cases.

3 License

The software is licensed under the ParaView License 1.2.

4 Installation

The reader can be installed as either plugins or a builtin reader.

  • If one chooses to install the reader as plugins the main ParaView sources does not have to be modified. Thus in general installing as plugins is recommended.
  • Installing as a builtin reader is meant for Linux package maintainers who intend to distribute their own versions of ParaView sources and binaries.

4.1 Prerequisites

  • CMake 2.6 or later is required.
  • The reader has absolutely no dependence on any of the OpenFOAM libraries (which is why the reader is called native). However the reader can be installed somewhat easier as plugins if installed with ParaView that comes with the ThirdParty package of OpenFOAM as shown below.
  • When configuring the reader with CMake, a system POSIX regex (regular expression) library is searched for and the reader uses the library if found in order to support regex'ed dictionary keyword syntax. If one is not found but the reader is built with Visual Studio 2008 SP1 or later, the regex library in STL TR1 extension that comes with Visual Studio 2008 SP1 or later is used instead. If none were found, the regex library included in VTK is used as the final fallback option. This is because at least a pattern in the extended regular expression (ERE) is known not supported by the VTK regex library. Hence on Windows, building the reader with Visual Studio 2008 SP1 or later is strongly recommended.

4.2 Install as plugins (Linux and OS X)

4.2.1 Building and installing ParaView with parallelization support

If you only want to read decomposed cases in serial, the reader works without parallelization support of the main ParaView build. However you would naturally want to turn it on for making full use of the capability of the reader. In order for ParaView to work in parallel, one has to do a full build, installation and setup of ParaView. See

http://paraview.org/Wiki/ParaView:Build_And_Install
http://paraview.org/Wiki/Starting_the_server

for full instructions. When configuring with CMake, at least the following variables should be set:

BUILD_SHARED_LIBS = ON
CMAKE_BUILD_TYPE = Release
PARAVIEW_USE_MPI = ON

. After installation, do not remove the ParaView build directory but keep it since it is required in building the plugins afterwards.

Alternatively, a parallelized ParaView can be built using the OpenFOAM ThirdParty source package by issuing the following commands under OpenFOAM environment:

cd $WM_THIRD_PARTY_DIR
./makeParaView -mpi

4.2.2 Building and installing the plugins

Create a build directory for the plugins and point CMake from the build directory to the top directory of the reader source tree (the directory where the README file is in).

mkdir <the plugin build directory>
cd <the plugin build directory>
ccmake <the top directory of the reader source tree>

Then set

CMAKE_BUILD_TYPE = Release
CMAKE_INSTALL_PREFIX = <one of the local plugin directories of the ParaView installation>
CMAKE_OSX_ARCHITECTURES = <the value used for the main ParaView build>
ParaView_DIR = <the directory where ParaView was built>

where CMAKE_OSX_ARCHITECTURES is only required under OS X. If one is unsure about where to install the plugins, the plugin directories can be checked by launching ParaView and choosing the Tools -> Manage Plugins/Extensions... menu. There one will see "Local plugins are automatically searched for in..." followed by a list of directories. Alternatively, if the plugins are being built within OpenFOAM environment in conjunction with the ThirdParty ParaView, all of these variables are set automatically as default values.

Then build and install the plugins.

make
make install

By these steps the reader and the UI plugins will be installed to the local plugin directory.

[!!IMPORTANT!!] ParaView may have different remote plugin directories than the local plugin directories when in client/server mode. In such cases the installed server-side plugin under the local plugin directory must be manually copied (or symbolic linked) by hand to one of the remote plugin directories. To check remote plugin directories, start ParaView in client/server configuration and choose Tools -> Manage Plugins/Extensions... . Attempting to read OpenFOAM cases in client/server mode without the plugin loaded as a remote plugin will crash ParaView.

4.3 Install as plugins (Windows)

The overall installation steps are identical to those for Linux and OS X except that one would probably use cmake-gui instead of ccmake and Visual Studio IDE (open Project.sln under the plugin build directory, set Configuration to Release and build ALL_BUILD followed by INSTALL) instead of make. The reader has been only tested with Visual Studio, and as written in the Prerequisites section, Visual Studio 2008 SP1 or later is strongly recommended. Building under MinGW has not been tested.

[Tip] One might want to take care about the manifest file of the Visual Studio 2008 SP1 runtime DLLs if the binary is intended to be deployed without requiring to install redistributable runtime DLLs separately.

4.4 Install as a builtin reader

Follow the "Install by patching the ParaView sources" section of INSTALL.special in the source package. After that, build ParaView as usual.

4.5 Install as plugins for Salome ParaViS module

Follow INSTALL.special in the source package.

5 Usage

In order to open OpenFOAM case, either

  • open system/controlDict (which only works for the development version), or
  • create an empty stub file <caseName>.foam right under the case directory, where <caseName> is an arbitrary string other than those that starts with "controlDict," and open <caseName>.foam

There is also a script for user convenience that works like paraFoam, called pf. The script creates the stub file and launches ParaView in background. For available options, run

pf -help

in terminal.

For general operations of the reader, see readerPanel.pdf.

6 Notes (general)

  1. Dictionary syntax ~OpenFOAM expands only to $HOME/.OpenFOAM where $HOME is the home directory of the user.
  2. The #remove dictionary directive is not supported.
  3. The builtin cell-to-point filter works like a Cell Data to Point Data filter in ParaView in that it just takes the average of cell values connected to a point. The difference is that the builtin filter takes boundary patch values into account. The filter is faster but less accurate than the volPoint interpolator in paraFoam, which further does inverse distance weighting of cell values. The cell-to-point filter is still computationally demanding thus can be turned off by unchecking "Create cell-to-point filtered data" on the reader panel.
  4. In order to create slices with volField data one may have to extract internal mesh or turn off reading patches in the reader panel before running the Slice filter, otherwise the sliced data may be garbled.
  5. When the List timesteps according to controlDict checkbox is turned on, the reader lists time instances according to descriptions in controlDict when (adjustTimeStep, writeControl) == (yes, adjustableRunTime) or (no, timeStep) (i. e. writing interval is supposed to be constant in simulated time), or otherwise, lists all valid time directories.
  6. The reader lists field names according to the "object" entry in FoamFile header, whereas paraFoam lists according to the file name of the object. Hence a valid FoamFile header is required for every object.
  7. Reading cellZones for polyhedral mesh with the Read Zones feature may cause ParaView to thrash.
  8. The reader only takes the "value" and "uniformValue" entries into account for boundary fields. If none of the entries exists, the corresponding patch-internal field values are used (i. e. equivalent to zeroGradient b. c.).
  9. When watching running case, one may occasionally see reader errors due to race conditions where the reader reads up until the end of file while the file is being written. Although the developer has put much effort in avoiding crashes in such cases, there may still be ones. Doing important tasks while watching case is thus not recommended.
  10. Multi-region case is detected by existence of mesh files under subdirectories found in first two time directories. If a case is determined to be a multi-region case, the selection of internalMesh of the default region in the reader panel is turned off by default.
  11. The variable expansion follows the original OpenFOAM 1.6 behavior in that variables match regex'ed keywords, whereas they do not in 1.6.x or later.

7 Notes (Parallel-specific)

  1. The Case Type selection combo box determines whether the case to be read is a reconstructed case (a serial case) or a decomposed case (a case decomposed into processorX/ subdirectories). The reader can read decomposed cases even when ParaView is run in builtin server (serial) mode. If ParaView is running in client/server mode and the servers (pvservers) are running in parallel, the decomposed mesh regions are read in parallel.
  2. The number of decomposed mesh regions and the number of pvserver processes do not have to be identical, with a known exception of the note 6 below. Processor subdirectories are detected by server process 0, and each processorX/ subdirectory is assigned to a server process in an interleaved way. For example, if one has 5 processor subdirectories and running 2 pvservers, the pvserver process 0 reads processor0/, processor2/ and processor4/ subdirectories while pvserver process 1 reads procssor1/ and processor3/ subdirectories. Which process owns which decomposed regions can be checked by Filters -> Process Id Scalars.
  3. Timesteps are taken from a first processor subdirectory (typically processor0/) by server process 0 and broadcasted to other processes.
  4. In client/server mode, reconstructed case is loaded by pvserver process 0. Merge Blocks -> D3 can be used in order to distribute the data. NB: Merge Blocks is still required nevertheless ParaView 3.6.1 and on D3 can be applied to multiblock data, due to an incompatibility with D3 of the reader which causes D3 to deadlock. The developer is working on resolving the issue.
  5. The reader does nothing about adding ghost cells. Hence one has to see processor boundaries when the geometry is represented in Wireframe or Surface. This could be especially problematic if one wants to extract surfaces. In order to remove internal processor boundaries from the output of the Extract Surface filter, run Merge Blocks -> D3 -> Extract Surface. Similarly, when the reader is run in serial or in builtin mode, the Clean to Grid filter can be used in order to remove internal processor boundaries.
  6. Beware that Stream Tracer may crash pvservers if more pvservers are run than the number of decompsed regions. The cause of the problem has not been tracked down yet, but so far the developer is regarding it is not in the reader but in ParaView because the crash can be reproduced with another reader as well. The problem was reported as bug #9787.
  7. The reader does not output processor boundary patches of decomposed regions. In order to see the processor patches, each processorX/ subdirectory has to be opened as a separate case.

8 Miscellaneous

  • The parallel extension part is quite a straightforward implementation of what are written in the Section 21.3 of The ParaView Guide.
  • In my testing I get typically 2.3x - 2.5x speedups in mesh loading time by 4 process parallel execution. However everything is not so rosy especially in that I often get slower rendering times by parallel executions. As no one but the developer being quite new to parallel visualization, the developer is interested in your findings. You are welcomed to post them to the forum.
  • The reader that comes with the Git head of ParaView 3.9 has experimental support for native polyhedron (vtkPolyhedron). The implementation in the reader, which the developer contributed, is experimental because vtkPolyhedron itself is still experimental. The reader has supported the development of the new cell type since its early stage by helping providing polyhedral test cases. Just uncheck "Decompose Polyhedra" in the reader panel in order to try out the cell type.

9 Downloads

Development version at GitHub:

  • The developer had given up the idea of creating a stable release for the moment since the reader project has to follow both ParaView and OpenFOAM developments, both of which are considered very active (the moving targets). NB: There can always be bugs, errors, crashes or even incomplete codes (the developer sometimes commits works in progress for backup purpose).

Downloads from other sources:

  • Contributed Linux/OS X ParaView packages with the reader included (the versions of the reader may not be up-to-date): Gentoo, Ubuntu 10.04, CentOS 5.x x86_64
  • Ubuntu 10.10 seems to have ParaView 3.8.1 with parallelization/Python scripting enabled in its packages (sudo apt-get install paraview).
  • Official releases of ParaView and VTK from Kitware: A version of the reader is a part of the official Kitware releases of ParaView and VTK. The version is based on a previous release of vtkPOpenFOAMReader-r64-20081005 since the developer had to do some specific works of addressing compilation issues in some older compilers. The most notable limitations of the version are
    • The version supports dictionary syntaxes up to OpenFOAM 1.5 (no support for regular expressions).
    • The reader does not have the custom Qt UI (the Reload and Watch buttons) since the developer used a GPLed version of Qt 4.3 at that time.

Technical documentation:

Past versions:

10 Feedbacks

If you found bugs or have comments, post to the native reader thread.

11 History

7islands 09:55, 20 September 2009 (UTC) (Takuya OSHIMA): Released 20090920. Changes from the 20081005 version are

  • Added support for extended dictionary syntaxes of OpenFOAM 1.6, notably the regex'ed dictionary keywords.
  • The reader now compiles with a drastically wider range of compilers. The tested compilers include many GCC versions from 3.3.2 to 4.4.1 (including Apple's compilers under 64bit mode), Intel Compiler 11/11.1, Sun Studio 12/12.1, Open64 4.2.1/4.2.2, Visual Studio 2003.net/2008SP1.
  • Added "watching a running case" functionality (which in fact has long been implemented in the svn-versions).
  • Better detection and handling of multi region cases. The reader now can read chtMultiRegionFoam/multiRegionHeater case. Note that one will still get an error about missing "uniform" keywords in buoyantPressure BC sections of the field files when reading the case as is. In order to eliminate the error, either add the uniform keyword to or remove entirely the value entries of the buoyantPressure sections of the field files and cahgeDictionaryDicts under the system subdirectory.
  • Added support for single precision binary format.
  • Improved performance in reading files in double precision binary format.
  • Improved installation steps.
  • Rewritten pvFoam script.
  • Changed the license of some more files to the BSDL.
  • Workaround for a locale problem in string-to-floating conversion under Qt 4.5/Linux.
  • Fixed many bugs, including crashes (thanks to all the reporters).
  • Other features that I don't remember.

7islands 06:10, 23 March 2009 (CET) (Takuya OSHIMA): Added a win32 binary package release.

7islands 06:13, 5 October 2008 (CEST) (Takuya OSHIMA): Released 20081005. Notable changes from the 20080831 snapshot are

  • Unified application interfaces of the serial/parallel readers. Both can be accessed by opening a .foam file. Subsequently, readers.xml no longer have to be patched -- which makes tracking the CVS head of ParaView easier.
  • Fixed several bugs, notably deadlocks.
  • Added lagrangian labelField support, casePath addition to output.
  • Added feature to change case without reinstanciating another reader.

7islands 06:57, 31 August 2008 (CEST) (Takuya OSHIMA): moved to Contrib section. Initial upload of the parallelized version.

7islands 02:58, 28 April 2008 (CEST) (Takuya OSHIMA): update for the 20080324 version.

7islands 09:18, 29 Dec 2007 (CET): some addenda.

7islands 04:36, 16 Dec 2007 (CET) (Takuya OSHIMA): Created this page.