Contrib/swak4Foam

From OpenFOAMWiki
Jump to: navigation, search
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.

Valid versions: OF version 16.png OF version 17.png OF Version 20.png OF Version 21.png OF Version 22.png OF Version 23.png OF Version 30ext.png OF Version 31ext.png

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

Contents

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.


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:

6 Downloading

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

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: OF Version 230.png OF Version 23x.png
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: OF Version 221.png OF Version 22x.png
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: OF Version 220.png
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.1 Development

The above SVN-repository is the current released version. The actual development version can be downloaded with Mercurial:

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

for the version that works with OpenFOAM 2.0 and above, as well as FOAM-Extend 3.0, you'll have to change to the appropriate branch with:

hg update port_2.0.x

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.

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 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.2 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 1.x 
http://sourceforge.net/p/openfoam-extend/svn/HEAD/tarball?path=/trunk/Breeder_1.7/libraries/swak4Foam
Released version for OpenFOAM 2.x 
http://sourceforge.net/p/openfoam-extend/svn/HEAD/tarball?path=/trunk/Breeder_2.0/libraries/swak4Foam
Development version 1.x 
http://sourceforge.net/p/openfoam-extend/swak4Foam/ci/default/tarball
Development version 2.x 
http://sourceforge.net/p/openfoam-extend/swak4Foam/ci/port_2.0.x/tarball

6.3 Mirror repositories

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

6.3.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:

7 Other

7.1 Further information

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

7.1.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.1.2 Examples at other sites

A nice tutorial on using swak4Foam is found here.

7.2 Bugreports

Please report bugs here: [2]

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

7.3 History

7.3.1 2010-09-13

First Release

7.3.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.3.3 2011-01-30

New release Changes (for details see README):

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

7.3.4 2011-04-20

New release

Changes (for details see README):

  • Stored variables
  • New utility funkyDoCalc
  • Calculation on sampled sets

7.3.5 2011-07-26

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

7.3.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.3.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.3.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.3.9 2012-10-18 - Version 0.2.1

Feature Release (see README)

7.3.10 2013-02-28 - Version: 0.2.2

Feature Release (see README)

7.3.11 2013-03-18 -Version : 0.2.3

Release to make swak work with OpenFOAM 2.2

7.3.12 2013-05-24 - Version: 0.2.4

Feature release for the 8th OpenFOAM

7.3.13 2014-01-24 - Version: 0.3.0

Feature release that introduces a parser for particles and other stuff

7.3.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

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