View source for Contrib/PyFoam/pyFoamCaseBuilder

= 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 <tt>pfcb</tt>)
* 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 <tt>pfcb</tt>-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

= Case Description Files – pfcb (PyFoamCaseBuilder)-files =
''Note: Building these pfcb-files is very much alike to programming''

== 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 <tt>casebuilder.dtd</tt> 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'')

== 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>
<?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>

</xml>


The main parts of the file are

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

=== 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

=== 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

=== Mesh preparation ===
There are two ways to prepare the mesh:

# By running a utility on the case
# By copying it from another case

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

==== 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

==== 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

==== 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

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

== pyFoamCaseBuilder.py – A command line interface ==
With this command-line utility the user only has to specify

# The name of the pfcb-file
# The name of the case
# 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.

== 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)

[[Image:CaseBuilderACase.png|frame|50px|A template being filled out in "A poor man's FoamX"]]
[[Image:CaseBuilderOverview.png|frame|50px|Browsing the available templates]]

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

== 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)

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