Contrib/PyFoam/pyFoamCaseBuilder

1 Overview

The purpose of the CaseBuilder is to build OpenFOAM cases that are ready to run, minimizing the amount of user inputs.

The CaseBuilder is split into two parts:

• the backend that reads the input and generates the part
• the frontend that interacts with the user

Input files required by the case builder are:

• the description file (usually with the extension pfcb)
• a template case from which files are copied and manipulated

The required input from the user is:

• The name of the destination case
• A set of parameters specified in the pfcb-file
• A mesh (which follows some conventions for the naming of the boundary patches)

Using these inputs the CaseBuilder generates a case that should be ready to run

2 Case Description Files – pfcb (PyFoamCaseBuilder)-files

Note: Building these pfcb-files is very much alike to programming

2.1 XML and DTD

Pfcb-files are XML-files. These are tedious to edit by hand, but with a file that describes the format and an editor that can use that format description it is more a „point and click“-experience.

The description of the pfcb-files is found in the file casebuilder.dtd that comes with pyFoam. When editing a pfcb-file point the XML-editor to that file and it should ensure that you only add „valid“ elements and tags (Note: I use for instance the XML-mode of (X)Emacs for editing – but I use Emacs for everything)

2.2 Structure of the files

Note: this only gives an overview of the files. The format might slightly change in future releases of PyFoam

A pfcb-file would look like this:

 
<?xml version="1.0"?>
<!DOCTYPE casebuilder 
  SYSTEM  "casebuilder.dtd" 
>
<casebuilder name="simpleFluent" 
  description="simpleFoam-case with a FLUENT-mesh" 
  template="$FOAM_TUTORIALS/simpleFoam/pitzDaily">
  <helptext>Lange Hilfe</helptext>
  <arguments>
    <arg name="mshfile" description="The FLUENT-mesh file"
      default="test.msh">
      <verify>
        <validator type="file"/>
      </verify>
    </arg>
    <arg name="vInlet" description="Velocity at the inlet" default="(1 0 0)"></arg>
    <arg name="skalierung" description="Scaling of the dings" default="0.001"></arg>
    <argumentgroup name="Fluid" description="Properties of the fluid">
      <arg name="dVisc" description="The dynamic viscosity" default="1e-5">
        <verify>
          <validator type="float" min="0"/>
        </verify>
      </arg>
      <arg name="density" description="The fluid density" default="1.2">
        <verify>
          <validator type="float" min="0"/>
        </verify>
      </arg>
    </argumentgroup>
  </arguments>
  <variables>
    <var name="kVisc" description="The kinematic viscositiy">
kVisc=float(dVisc)/float(density)
</var>
  </variables>
  <meshpreparation> 
    <utility command="fluentMeshToFoam" arguments="%(mshfile)s -scale %(skalierung)s"/>
  </meshpreparation>
  <files>
    <boundaries>
      <boundary name="inlet" description="Velocity inlet"
        pattern="in.+"/>
      <boundary name="outlet" description="Pressure outlet"
        pattern="out.+"/>
      <boundary name="wall" description="Walls" pattern="wall.+"/>
    </boundaries>
    <parameterfiles>
      <directory name="constant">
        <file name="RASProperties">
        </file>
        <file name="transportProperties">
          <parameter name="['nu'][2]" value="%(kVisc)s"/>
        </file>
      </directory>
      <directory name="system">
        <file name="controlDict">
        </file>
        <file name="fvSolution">
        </file>
        <file name="fvSchemes">
        </file>
      </directory>
    </parameterfiles>
    <fieldfiles>
      <field name="p">
        <ic value="0"/>
        <bc name="wall" type="zeroGradient"/>
        <bc name="inlet" type="zeroGradient"/>
        <bc name="outlet" type="fixedValue"
          parameters="'value':'uniform 0'"/>
        <defaultbc type="zeroGradient"/>
      </field>
      <field name="U">
        <ic value="(0 0 0)"/>
        <bc name="wall" type="fixedValue" parameters="'value':'uniform (0 0 0)'"/>
        <bc name="inlet" type="fixedValue"
          parameters="'value':'uniform %(vInlet)s'"/>
        <bc name="outlet" type="zeroGradient"/>
        <defaultbc type="fixedValue" parameters="'value':'uniform (0 0 0)'"/>
      </field>
      <field name="k">
        <ic value="0.25"/>
        <bc name="inlet" type="fixedValue"
          parameters="'value':'$internalField'"/>
        <defaultbc type="zeroGradient"/>
      </field>
      <field name="epsilon">
        <bc name="inlet" type="fixedValue"
          parameters="'value':'$internalField'"/>
        <ic value="15"/>
        <defaultbc type="zeroGradient"/>
      </field>
    </fieldfiles>
  </files>
</casebuilder>
 

The main parts of the file are

2.2.1 The basic specification

These are in the root element:

• the name of the template
• a one line description
• the location of a template case from which files are to be copied

In addition there can be an optional longer help-text that can be displayed by a GUI.

2.2.2 The arguments

This is a list of the parameters that the user is asked for. The things that are specified here are:

• a short name for the parameter
• a short help text
• an optional default value for the parameter
• optionally a small Python-code-snipplet can be added. This is used to verify whether the user-input is valid

2.2.3 Variables

These are optional variables that are computed from the user input. The things to be specified are:

• the name
• a description
• a Python-code-snipplet that calculates the value of the vaiable

2.2.4 Mesh preparation

There are two ways to prepare the mesh:

1. By running a utility on the case
2. By copying it from another case

2.2.5 The files

This specifies the files that have to be generated in the target case.

2.2.5.1 Boundaries

This enables the case-builder to tell from the name of the patch what kind of boundary-condition should be applied. The specification consists of

• the name of the boundary condition
• a regular expression that the name of the patch must match (so the mesh has to be generated with this in mid)
• A short description of the file

2.2.5.2 Parameter-files

Files that are „independent“ of the mesh. For each directory of the template case the files that should be copied are specified. If certain-values should be modified according to the user input this is specified with a parameter-element

2.2.5.3 Field-files

These are files that depend on the mesh (where the boundary-conditions have to be generated). The templates for these files are copied from the initial-time directory of the template-case. Three kinds of elements are specified:

• The initial value of the file (currently only uniform is possible)
• The default boundary-condition. This is the boundary condition that is written for a patch if no specific BC is specified for it
• Boundary conditions for specific patch types. The name that is specified here must be found in the boundaries specified above

Each boundary condition has a type-tag that is the name of the OpenFOAM-boundary type and an optional tag parameters that contains a Python-dictionary with the additional values necessary for that boundary condition

3 Implemented FrontEnds

Currently two front-ends are implemented. Others (especially graphical) are possible, but currently not planned.

3.1 pyFoamCaseBuilder.py – A command line interface

With this command-line utility the user only has to specify

1. The name of the pfcb-file
2. The name of the case
3. The paramters in the order in which they appear in the pfcb-file

The utility then builds the case. An example usage would be

pyFoamCaseBuilder.py simpleFluent.pfcb testIt test.msh "(5 0 0)" 0.01 1e-4 1.2

to build a case testIt from a FluentMesh test.msh that is scaled in centimeters.

3.2 pyFoamAPoMaFoX.py – A text interface

A simple text interface that allows to browse the available pfcb-files (if none was selected on the command line) and afterwards fill out the values for the parameters of the selected pcfb-file.

Please note that

• you need to install the urwid library to be able to run it
• it is only a proof of concept (people here talk of „catching eye cancer“ when looking at the colors of that thing – see pictures)

A template being filled out in "A poor man's FoamX"

Browsing the available templates

4 Examples

Currently there are two examples for pfcb-files that come with pyFoam

4.1 simpleFluent

For this example you have got to provide a Fluent-mesh. The user only has to provide some basic quantities (density and kinematic viscosity). It generates a simpleFoam-case (the dynamic viscosity is calculated from the user input)

4.2 lesSnappy

This copies the mesh from a snappyHexMesh-“case“ and generates an oodles-case