-- mode: org --

#+TITLE: =README= for =swak4Foam= - Version for OpenFOAM 2.x

• Description A collection of libraries and tools that let the user handle OpenFOAM-data based on expressions

• About this document ** Scope This file gives an overview of =swak4Foam= and a history of the features. It is not a canonical documentation. ** Technical This file is written in the mighty =org-mode= (see [[http://orgmode.org/]]) a markup/outline-mode for (X)Emacs. Using this mode it can be easily (using 3 keystrokes ... it's Emacs) to PDF or HTML to make it more readable (and add a table of contents).

  Please don't try to "beautify" it with any other text editor as this will surly mess up the markup (and keeping the file /org-compatible/ outside of the =org-mode= is a pain in the neck.

• Contributors etc ** Original Author Bernhard Gschaider (bgschaid@ice-sf.at) ** Current Maintainer Bernhard Gschaider (bgschaid@ice-sf.at) ** Contributors In alphabetical order of the surname

  • Martin Beaudoin :: =trackDictionary= in =simpleFunctionObjects=
  • Martin Becker :: The =potentialPitzDaily=-case (demonstrating a problem with =groovyBC=)
  • Oliver Borm :: =patchMassFlowAverage= in =simpleFunctionObjects=
  • Peter Keller :: =sprinklerInlet=-case
  • Martin Kroeger :: =mtv= surface writer in =simpleFunctionObjects=
  • Andreas Otto :: fixed the =circulatingSplash=-case
  • Alexey Petrov :: =pythonFlu=-integration
  • Bruno Santos ::
    • Compilation with Intel compiler and Mingw
    • Rewrite of =mybison= and =myflex= to allow parallel compilation with =WM_COMPPROCS= If anyone is forgotten: let me know

  According to the commits in the =mercurial=-repository (and the repositories of the projects from which swak emerged) contributors are (ordered by the year of their first contribution):

  • 2006-2013 Bernhard F.W. Gschaider bgschaid@ice-sf.at
  • 2008 Hannes Kroeger (hannes@kroegeronline.net)
  • 2008-2009, 2012 Martin Beaudoin, Hydro-Quebec (beaudoin.martin@ireq.ca)
  • 2010 Marianne Mataln mmataln@ice-sf
  • 2010 Oliver Borm (oli.borm@web.de)
  • 2011 Alexey Petrov alexey.petrov.nnov@gmail.com
  • 2011 Petr Vita petr.vita@unileoben.ac.at
  • 2012 Bruno Santos wyldckat@gmail.com
  • 2013 Georg Reiss georg.reiss@ice-sf.at ** Documentation See: http://openfoamwiki.net/index.php/contrib/swak4Foam

• Installation/Compilation ** Requirements

  • Version 2.0, 2.1 or 2.2 of OpenFOAM (a version that works with 1.6, 1.6-ext and 1.7 is available separately)
    • The =finiteArea=-stuff will probably work with version 2.0-ext (once that is available)
  • the compiler generators =bison= and =flex=
    • bison :: =swak4Foam= is known to work with =bison= version 2.4 and higher. Version 2.3 compiles but the plugin-functionality does not work correctly
    • flex :: since the introduction of the plugin functions at least a flex version of =2.5.33= is required (=2.5.35= is the lowest confirmed version)

  Both of these are mainstream packages (they are for instance needed to compile =gcc=) and should exist on every Linux distribution. Use the package manager of your distribution to install them and only if the compilation process of =swak4Foam= complains about too low versions try to install them from other sources.

  =swak4Foam= tries to keep the requirements on these as low as possible and sometimes lower versions than the ones reported may work. If they do please report so.

  The version of bison can be checked with : bison -V The version of flex with : flex -V ** Building : wmake all at the base directory should build all the libraries and tools.

  Rerun the command to make sure that there was no problem with the compilation (this should be quite fast and only report libraries being created and some administrative stuff) *** Additional configuration Some features (currently only the =Python=-integration may need third party software. The paths to these packages can be configured in a file =swakConfiguration= (an example file =swakConfiguration.example= is provided). If that file is not present these unconfigured features will not be compiled.

  Environment variables that can be set in this file are:

  • SWAK_PYTHON_INCLUDE :: Path to the =Python.h= file of the used =python=-installation
  • SWAK_PYTHON_LINK :: Options to link the =python=-library to the library for the =python=-integration
  • SWAK_USER_PLUGINS :: A list of paths separated by semicolons. These are the directories of libraries with function-plugins. They are compiled in the course of the normal =swak=-compilation. This makes sure that they are consistent with the =swak=-release in the case of an update
  • SWAK_COMPILE_GRAMMAR_OPTION :: Additional compiler switches for the C-files generated by =bison=. Usually used if the default optimization switches are too aggressive and compilation takes to long (then a value like =-O0= would for instance switch off all optimizations) *** Possible compilation failure with old 2.0.x-versions With older versions of 2.0.x (or 2.0 or 2.0.1) it is possible that the compilation of =swakCodedFunctionObject= will fail. In that case remove the last parameter to the =codedFunctionObject=-constructor in =swakCodedFunctionObject.C= (it is clearly marked by a comment) *** Special versions of the python integration Note: This section is very special and won't be needed by most people

  The library =libswakPythonIntegration.so= links against a specific version of the python library. In certain circumstances (for instance the OS of the cluster is different from the one that swak was compiled on) this python-version is not available on the target machine. While all other parts of swak will work the python-integration won't load on the target machine. To fix this problem a workaround is provided:

  The script =maintainanceScripts/makeSpecialPythonLibrary.sh= compiles a special version of the =libswakPythonIntegration.so= that is identified by an additional suffix (for instance the suffix =Cluster= makes a file =libswakPythonIntegrationCluster.so=). That script has to be run on the target system and needs 3 parameters:

  1. =SWAK_PYTHON_INCLUDE=
  2. =SWAK_PYTHON_LINK=
  3. The suffix For instance : ./maintainanceScripts/makeSpecialPythonLibrary.sh -I/opt/local/Library/Frameworks/Python.framework/Versions/2.5/include/python2.5 "-L/opt/local/lib -lpython2.5" Version2.5 compiles a version for an old python.

  To enable the python-integration in =libs= in =controlDict= both python-integrations have to be specified. One of them will fail on each machine (because the required python-library is not there), the other one will provide the python-functionObjects.

  Note: the special libraries won't be updated automatically on the target system. Doing so is the responsibility of the user. ** Global installation If the libraries and utilities are considered stable and the should be available to everyone (without having to recompile them) the script =copySwakFilesToSite.sh= in the directory =maintainanceScripts= can be used to copy them to the global site-specific directories.

  The script =removeSwakFilesFromSite.sh= in the directory =maintainanceScripts= removes all these files from the global directories. The =removeSwakFilesFromLocal.sh= does the same for the user directories (this makes sure that no self-compiled version /shadows/ the global version (which would lead to strange results)

  There is a =Makefile= attached. =make globalinstall= compiles =swak4Foam= and installs it into the global directories

  Note: Due to the order in which library direcories are searched for with =-L= a global installation might break the compilation. If you don't know what this means: don't attempt a global installation ** Packaging *** Debian The command =build dpkg= builds a Debian/Ubuntu package for the currently enabled OpenFOAM-package. Note:

  • it is assumed that the currently used OF-version was also installed by the package manager
  • the =dev= package is built but poorly maintained Changes in the packaging should be done in the branch =debianPackaging= of the Mercurial-repository and later be merged to the =default=-branch.

  Packaging for OpenFOAM 2.x should be done in the branch =debianPackaging_2.x=

  Note: Due to the problem described with the global installation it might be necessary to deinstall a previously installed package to successfully build a new package

• Contents ** Libraries Collection of Libraries *** =swak4FoamParsers= The basis of =swak4Foam=: the expression parsers with the logic to access the /OpenFOAM/ data-structures.

  None of the other software pieces compile without it.

  Also defines a subclass to =DataEntry= that uses =swak=-expressions and a function object =initSwakFunctionObject= that might be used if this fails *** =simpleFunctionObjects= A collection of function objects that was previously separately available at http://openfoamwiki.net/index.php/Contrib_simpleFunctionObjects.

  Provides consistent output of values (on patches and fields) and more. *** =groovyBC= Implements the infamous =groovyBC=. A boundary condition that allows arbitrary expressions in the field-file *** =swakFunctionObjects= Function objects that have no additional requirements. Mainly used for manipulating and creating fields with expressions

  • addGlobalVariable :: Adds a variable to a global swak-namespace. Mainly used for