Contrib/swak4Foam

Look. If this works, it'll keep us from getting caught. If it doesn't, it'll keep us from getting old.

MacGyver. Master of the knife

A library that combines the functionality of groovyBC and funkySetFields: it offers the user the possibility to specify expressions involving the fields and evaluates them. This library offers a number of utilities (for instance funkySetFields to set fields using expression), boundary conditions (groovyBC to specify arbitrary boundary conditions based on expressions) and function objects that allow doing many things that would otherwise require programming.

Currently this page is incomplete. Please have a look at those 2 pages (groovyBC and funkySetFields) for further information.

For the impatient: to compile the latest released version use Mercurial (on some machines you have to install Mercurial) to download the sources (there are references to a git-repository floating around: do not use it. It is only a copy of the Mercurial repository and possibly outdated):

 
hg clone http://hg.code.sf.net/p/openfoam-extend/swak4Foam swak4Foam
cd swak4Foam
./AllwmakeAll

Newer OpenFOAM versions might not be supported by the released version. Try

 
hg update develop

to change to the latest (possibly unstable) versions of the sources

Valid versions:

This page is only a stub. I'll finish it when I find time. If you feel that you can improve it: go ahead

1 About

swak4Foam stands for SWiss Army Knife for Foam. Like that knife it rarely is the best tool for any given task, but sometimes it is more convenient to get it out of your pocket than going to the tool-shed to get the chain-saw.

2 Building

This is a short overview of the installation process. A more detailed description is found here (consult these pages if you have problems during installation)

In the directory of the sources just do

wmake all

or

./Allwmake

and everything should be built. It is not possible (at least for a novice) to just build selectively parts (like groovyBC) on their own.

Note: building swak4Foam installs it into FOAM_USER_LIBBIN for the current user. So if it built as root (or another administrative account) it is not usable from another account (or in other words: every user must compile swak4Foam for himself separately. There are ways to install it for all users. They are documented but you must find the way there yourself as a test to make sure you know what you're doing as doing this wrong may introduce very peculiar problems)

For further information please refer to the the README.

Tip

If using a GCC or ICC compiler (and not clang), then before running one of the commands above, the following command can define the number of cores to be used for a faster build process:

export WM_NCOMPPROCS=4

Where 4 means that the machine has got 4 processor cores. Using a value larger than the number of cores the machine has got, can risk using more memory than the machine has got and leading to a freeze or crash.

Note

bison>=3.x is not compatible. Therefore, after you download the file from the link above and unpacked it, then go into the command line and run

./maintainanceScripts/compileRequirements.sh
./Allwmake

2.1 Checking the version

If there is already an installation of swak4Foam you can check the version by simply entering

funkySetFields

This ends with an error message, but below the usual OpenFOAM-banner you find the version of swak4Foam and the release date. If there is no swak-version then the installation is older than 0.2.0 (the first version to have this banner)

2.2 Preparing the controlDict

The following libs need to be added to the file controlDict, e.g.:

/OpenFOAM/name-2.1.0/run/casename/system/controlDict

Insert the following lines near the top of the controlDict file:

libs (
      "libOpenFOAM.so"
      "libsimpleSwakFunctionObjects.so"
      "libswakFunctionObjects.so"
      "libgroovyBC.so"
     );

3 Contents

3.1 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

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

simpleSwakFunctionObjects

Function objects based on the simpleFunctionObjects-library (which is a prerequisite for compiling it). Evaluate expressions and output the results

swakSourceFields

Field that is calculated from an expression. To be used as source-term or coefficient in some solver

swakTopoSources

topoSources for cellSet and faceSet. Can be used with the cellSet and faceSet-utilities

pythonIntegration

Function object which allows inclusion of Python code directly into an OpenFOAM Simulation run. Various inline code snippets or python script files can be specified to be called once at the start of a run, once at the end of a run and during each time-step during a simulation.

3.2 Utilities

funkySetFields

Utility that allows creation and manipulation of files with expressions

funkySetBoundaryField

Sets any field on a boundary to a non-uniform value based on an expression. Acts without deeper understanding of the underlying boundary condition

replayTransientBC

Utility to quickly test whether a groovyBC gives the expected results. Writes the specified fields with the applied boundary condition but doesn't do anything else. Can be used for other transient BCs as well

3.3 Examples

Have a look at the README and the files to understand how to use things

4 Expression

These are the core of it. Expressions can be used for

• internalFields (basically the functionality of expressions in funkySetFields.
• patchFields (basically the functionality of expressions in groovyBC
• cellSet, faceSet, cellZone, faceZone. Only a subset of the functionality of expressions above is supported
• surface. Calculations on sampledSurface. Only a subset of the functionality of expressions above is supported

4.1 Accessing external expressions

The syntax for this is slightly different from external expressions in groovyBC (the change of syntax was chosen to avoid clashes with valid patch or zone names).

The destination for an external expression is enclosed in {}. It can consist of three parts

1. entity type (if none is given, then patch is assumed. Unless no name is given, then internalField is assumed). Valid types are
   • internalField
   • patch
   • cellZone
   • faceZone
   • cellSet
   • faceSet
   • surface
2. entity name
3. mesh region (if none is given, then the current mesh is assumed)

Not all three parts have to present. In the general form it is written as {type'name/region}. So

pInlet{inlet}=average(p);

is the average pressure on the inlet.

pControl{faceZone'control/otherMesh}=average(p);

is the average pressure on a faceZone on another mesh.

External values can only be used if they are homogenous (so they should either be a min, max, sum or average)

4.2 Random notes on the expression syntax

Some changes to the original syntax of groovyBC and funkySetFields (these remarks should become obsolete once there is a canonical list of functions here).

• For faceSet and faceZone a pseudo-function flip() is defined which is either +1 or -1. For faceZone this is the flipMap (-1 if the flipMap is true for a face). For a faceSet named (for instance) foo it is defined if a cellSet of the name fooSlaveCells is defined (this follows the convention of the setsToZones-utility. The main purpose of this function is to get consistent mass-flows on faces (phi*flip() takes into account the orientation of the faces)
• there is a new pseudo-function cpu() that returns the number of the current CPU for parallel runs
• the pseudo-function id() returns the cell/face-id

5 Usage examples

Until there is a 'read' documentation this section links to a number short examples how swak4Foam can be used for common tasks:

• Calculate the mass flow on patches and faceSets/zones
• Calculate the pressure difference between a patch and other entities
• Initialize a random velocity field
• Calculate the velocity of a droplet
• Calculate the forces on selected parts of a patch

6 Downloading

Currently the recommended way to download swak4Foam is the Mercurial repository. The only supported binaries are the Docker containers

6.1 Mercurial repository

The source code can be downloaded with Mercurial:

hg clone http://hg.code.sf.net/p/openfoam-extend/swak4Foam openfoam-extend-swak4Foam

(which can be viewed here)

The local copy is automatically set to the default-branch which is the version that works with OpenFOAM 2.0 and above, as well as FOAM-Extend 3.0. It occasionally receives updates between releases

To get the development branch do

hg update development

If you still need older Foam-versions you'll have to change to the appropriate branch with:

hg update master_1.x_legacy

If you want to contribute (which is encouraged. Code or examples. Whatever you want) please contact Bgschaid and we'll set something up for write access or issue a merge request through Sourceforge. Also read the section on development in the README.

An alternate mercurial repository is found at BitBucket. It is only meant as a backup for the repository at Sourceforge and will receive pushes less frequently than the Sourceforge repo.

6.1.1 Changing branches for existing clones

The default-branch used to be (before July 2015) the branch for OpenFOAM 1.x. Existing working copies can be updated (and changed) with

hg pull
hg update master_1.x_legacy

The branch for OpenFOAM 2.x and foam-extend 3.x used to be port_2.0.x. If you have a local clone that you want to keep using update it with

hg pull
hg update default

6.1.2 Updating existing working copies

If you downloaded the repositories before January 2013 and want to keep those working copies see this article on information how to switch them to the new links.

6.1.3 Cloning with git

For those who still insist on using git: you can use this helper to clone the repository:

 
git clone hg::http://hg.code.sf.net/p/openfoam-extend/swak4Foam openfoam-extend-swak4Foam
git checkout branches/develop

This should allow pushing back to the repository.

6.2 Docker containers

Some containers that include swak4Foam can be found at DockerHub and are described at this page about an Ansible build script.

6.3 Tarballs

Tarballs are currently not officially provided. It might be possible to download them from Sourceforge (this might take some time as Sourceforge builds the tarball for downloading, nonetheless check this ticket to double-check if it works as intended):

Released version for OpenFOAM 2.x 

http://sourceforge.net/p/openfoam-extend/svn/HEAD/tarball?path=/trunk/Breeder_2.0/libraries/swak4Foam

• The tarballs of the old release (0.2.3) can be downloaded here for OpenFOAM 2.x and OpenFOAM 1.x.

Released version for OpenFOAM 1.x 

http://sourceforge.net/p/openfoam-extend/svn/HEAD/tarball?path=/trunk/Breeder_1.7/libraries/swak4Foam

Development version 1.x 

http://sourceforge.net/p/openfoam-extend/swak4Foam/ci/develop/tarball

Development version 2.x 

http://sourceforge.net/p/openfoam-extend/swak4Foam/ci/port_2.0.x/tarball

6.4 Mirror repositories

The following subsections list possible mirrors (most unofficial) for swak4Foam:

• unofficial-extend-project-mirror.github.io

It is not recommended to use this (or any other git) mirror for development if you want your modifications included in the main repository. The development of this project is done in a Mercurial repository and insisting on git adds extra work on the maintainer (to clone the development repository into git in a way that can be pushed back to Mercurial see the the recipe above)

6.4.1 unofficial-extend-project-mirror.github.io

The project unofficial-extend-project-mirror.github.io unofficially mirrors the source code repositories considered most important from Extend Project's Git and SVN repositories. The following repositories are available and respective possible download methods:

• swak4Foam for OpenFOAM 1.x is provided in the repository openfoam-extend-Breeder1.7-libraries-swak4Foam:
  • Git:

    git clone https://github.com/Unofficial-Extend-Project-Mirror/openfoam-extend-Breeder1.7-libraries-swak4Foam.git swak4Foam

  • ZIP: master.zip
  • tar.gz: master.tar.gz
• swak4Foam for OpenFOAM 2.x and FOAM-Extend 3.x is provided in the repository openfoam-extend-Breeder2.0-libraries-swak4Foam:
  • Git:

    git clone https://github.com/Unofficial-Extend-Project-Mirror/openfoam-extend-Breeder2.0-libraries-swak4Foam.git swak4Foam

  • ZIP: master.zip
  • tar.gz: master.tar.gz

6.5 Old SVN repository

The version that works with OpenFOAM 2.0 and above, as well as FOAM-Extend 3.0, can be found at:

svn checkout svn://svn.code.sf.net/p/openfoam-extend/svn/trunk/Breeder_2.0/libraries/swak4Foam/ swak4Foam_2.x

If you are unable to download with these commands, then check the Tarballs and Mirror repositories sections.

Further information is found in the README-file.

Warnings:

Valid versions:

swak4Foam 0.3.2 has a problem in building the library swakFunctionObjects. Bug and fix reported here: #229 solverPerformance in OpenFOAM 2.1 and 2.0 is hidden inside lduMatrix

Valid versions:

swak4Foam 0.3.2 has a problem in building the library simpleFunctionObjects.

• Fix provided here: swak4foam >>>> INSTALLATION PROBLEM - post #7
• Bug and fix reported here: #228 writeFieldsGeneralFunctionObject.C fails to build with OpenFOAM 2.2

Valid versions:

swak4Foam 0.3.2 has a few minor issues in building with OpenFOAM 3.0 and foam-extend 3.2. To solve the issue, use the master branch from the Mercurial repository, as explained here: Installation/swak4Foam/Downloading - swak4Foam development version for OpenFOAM 2.x/3.x/dev and foam-extend 3.x

Valid versions:

swak4Foam 0.3.0 does not work with OpenFOAM 2.3.0. Nonetheless, you can try to build the latest development version, which can be downloaded by following the instructions in section Development or Tarballs (be sure to download the development version of swak4Foam for OpenFOAM 2.x). (deprecated with the release of swak4Foam 0.3.1)

Valid versions:

There was yet another crucial change in the API for 2.2.x, where the timeSet method was added to the function objects (see this commit). The patch for swak4Foam 0.2.4 is provided in this post: post #8 (deprecated with the release of swak4Foam 0.3.0)

Valid versions:

Seems like there is a crucial change in the API between 2.2.0 and 2.2.x which makes compilation on 2.2.0 fail. If you use that version you'll have to apply a change described in this forum post (deprecated with the release of swak4Foam 0.3.0)

6.6 Obsolete version

The current version that works with 1.x-releases of OpenFOAM can be downloaded using this command:

svn checkout svn://svn.code.sf.net/p/openfoam-extend/svn/trunk/Breeder_1.7/libraries/swak4Foam/ swak4Foam_1.x

This version is outdated and should only be used if desparate

7 Other

7.1 FAQ

Some frequently asked questions are answered here

7.2 Further information

In addition to the material on this Wiki there are two presentations that show the capabiities of swak4Foma

• A presentation held at the 6th-OpenFOAM workshop (the case files described in the presentation)
• this presentation (held at the Austrian Usertgroup Meeting PFAU)
• This presentation from the 8th OpenFOAM Workshop gives an introduction to swak4Foam and showes the latest Features. The material mentioned is available here
• [1] (HTML5-browser required) held at PFAU 7.0 Austrian User Meeting introduces newer features like Lagrangian Particle Parser and advanced Python-integration
• There was a a basic training about swak4foam and PyFoam at the 9th OpenFOAM Workshop.
• Second training at the Workshop was about programming swak4Foam for which the materials are available here
• Presentation about state machines (a new feature in swak4Foam) given at PFAU 13
• Introductory training for swak4Foam and PyFoam at the 12th International OpenFOAM Workshop. This is a completely new training. An updated version of the Training held at the 2019 Workshop in Duisburg. The hopefully last version File:BernhardGschaider-OFW17 swakPyFoamBasicTraining.pdf with pointers to other material
• State and Solution: about advanced features of swak4Foam that allow modifying the numerics etc during the simulation. Presented at the 12th International OpenFOAM Workshop.
• A training about advanced topics in swak4Foam held at the 2019 Workshop in Duisburg
• A short presentation held at the Austrian User Group meeting on 2020-10-16 about simple region solvers a new feature of swak4Foam that allows using complete solvers as function objects
• From the 16th OpenFOAM-Workshop features of interest for developers (in combination with PyFoam)

7.2.1 Documentation with the sources

With the sources comes a README. It is written in org-mode and can easily be converted to PDF. The README can be found here for the 2.x-version and here for the 1.x-version.

There is also a reference manual in the folder Documentation which is not yet complete (but the section on expressions and general parameters is complete) but the existing parts are updated in parallel to the sources. A version can be found here.

7.2.2 Examples at other sites

A nice tutorial on using swak4Foam is found here.

7.3 Bugreports

Please report bugs here: [2]

Fixes will be usually pushed to the development repository and show up in the next release.

7.4 History

7.4.1 2010-09-13

First Release

7.4.2 2010-12-18

New release Most important changes:

• Parser for sampledSurfaces
• Multiline variables
• Two maintainance-scripts were added
• Parsers using 'external variables' are now run-time selectable

7.4.3 2011-01-30

New release Changes (for details see README):

• Library to deal with finiteArea in 1.6-ext
• Bug-fixes

7.4.4 2011-04-20

New release

Changes (for details see README):

• Stored variables

• New utility funkyDoCalc

• Calculation on sampled sets

7.4.5 2011-07-26

New release. Major change is support for OpenFOAM 2.0. For details see the README

7.4.6 2011-10-03

New release. Major changes are

• Support for programmingfunctionObjects (C++ and Python)
• Global variables
• Solving of PDEs (Laplacian and Transport equation) in functionObjects

For details see the README and this presentation (held at the Austrian Usertgroup Meeting PFAU)

7.4.7 2012-01-04

New release.Major improvements are:

• extension of the Field-parser to allow surface-fields and tensors
• conditional function objects (execute function objects on demand)
• improved Allwmake (catches common compilation problems)
• finiteArea now also supports the PDF-functionObjects
• and several other improvements

for a detailed list have a look at the relevant section of the README: for the 1.x-version or the 2.x-version

7.4.8 2012-04-13 - Version 0.2.0

New release. Improvements are (see README for full list):

• temporal operators ddt and oldTime. Other operators from fvc are added
• functions for location of minimum and maximum
• Field-parser now supports tensors and pointFields
• New variables for Python-integration
• boundary conditions groovyBCDirection and groovyBCJump
• fully parallel compilation

7.4.9 2012-10-18 - Version 0.2.1

Feature Release (see README)

7.4.10 2013-02-28 - Version: 0.2.2

Feature Release (see README)

7.4.11 2013-03-18 -Version : 0.2.3

Release to make swak work with OpenFOAM 2.2

7.4.12 2013-05-24 - Version: 0.2.4

Feature release for the 8th OpenFOAM

7.4.13 2014-01-24 - Version: 0.3.0

Feature release that introduces a parser for particles and other stuff

7.4.14 2014-07-11 - Version: 0.3.1

Feature release which adds support for OpenFOAM 2.3 and Foam-Extend-3.1. Also a number of features

7.4.15 2015-05-31 - Version: 0.3.2

Feature release that adds support for OpenFOAM 2.4 and Foam-Extend-3.2. Last version to support OpenFOAM 1.7 and older

7.4.16 2016-07-15 - Version: 0.4.0

Feature release that adds support for OpenFOAM 3.0, Foam-Extend-4.0 and OpenFOAM+ 3.0. Does not support OpenFOAM 1.7 and older any more

--Bgschaid 01:17, 14 September 2010 (CEST)