===== Installing an OpenFOAM application =====

To install an OpenFOAM application, you will need to

  - Setup the directory for your OpenFOAM application and versions
  - Setup a VALET package (or just add a ''<version>'' for an existing OpenFOAM application)
  - Setup your OpenFOAM application environment using ''vpkg_require <package>/<version>'' and build it using (Allwmake, wmake, etc.)

To run an OpenFOAM application, your job script would use the same ''vpkg_require <package>/<version>''.

==== Setup the application directory ====

We suggest using your workgroup work directory to setup your application directory.  For example, if user ''traine'' for workgroup '''it_css''' is installing the OpenFOAM application, ''sowfa'', then the application directory location might be ''$WORKDIR/traine/sowfa''.  Each version of ''sowfa'' will be installed in this location based on the version of OpenFOAM and compiler used to build it. For example, the directory ''$WORKDIR/traine/sowfa/2.0-OF2.1-gcc'' might be created for sowfa version 2.0 based on OpenFOAM version 2.1 compiled with gcc.

==== Setup a VALET package ====

If you already created a VALET package for your OpenFOAM, then skip to the section to edit your OpenFOAM application VALET package template, otherwise copy the OpenFOAM application template, ''/opt/shared/templates/gridengine/valet/openfoam-app.vpkg'', and name it appropriately for your application.  For example, if the OpenFOAM application is ''sowfa'', then your VALET package name, ''sowfa.vpkg'', should be copied into one of the following VALET locations

  * ''$WORKDIR/sw/valet''
  * ''$HOME/.valet/''

to automatically have VALET find the package.

<note>
Your VALET filename (e.g. ''sowfa.vpkg'') may use all lowercase letters, numbers, and hyphens or underscores. Also your ''$WORKDIR/sw/valet'' is only searched by VALET if your are in a workgroup.  Remember if you are creating a VALET package directory location for everyone in your workgroup, then make sure you use ''mkdir -m 1770 $WORKGROUP/sw'' and ''mkdir -m 1770 $WORKGROUP/sw/valet'' so these directories are writeable by others in your workgroup. 
</note>

=== Edit your OpenFOAM application VALET package template ===

Now edit the template (e.g. ''sowfa.vpkg'') to specify this version by doing the following 

== Change the package id ==

<code>
    <package
      xmlns="http://www.udel.edu/xml/valet/1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.udel.edu/xml/valet/1.0
                      http://www.udel.edu/xml/valet/1.0/schema.xsd"
      id="APPLICATION">
</code>
to match the name of your OpenFOAM application ''sowfa'' for VALET package, e.g. ''sowfa.vpkg''

== Change the package prefix directory ==

<code>
   <prefix>**DIRECTORY**</prefix>
</code>

to be the directory location containing the different versions of your OpenFOAM application.  For example,
      
<code>      
   <prefix>$WORKDIR/traine/sowfa</prefix>
</code>

== Add a version section for each OpenFOAM application version ==

<code>
    <version id="VERSION">
      <script shell="sh">openfoam.sh</script>
       <dependencies>
         <package id="openfoam/2.1.1-gcc"/>
       </dependencies>
    </version>
</code>

where ''VERSION'' should be replaced with the directory name for that particular version, e.g. "2.0-OF2.1-gcc" for the application located in
      
<code>
    $WORKDIR/traine/sowfa/2.0-OF2.1-gcc
</code>    

<note>
Naturally, if you require a different version of OpenFOAM and compiler for this version of your OpenFOAM application, change the dependency accordingly.
</note>

The ''openfoam.sh'' helper script is sourced automatically by an application's VALET setup; it sets ''WM_PROJECT_USER_DIR'' to the ''VALET_PATH_PREFIX'' based on the package version, then sources the ''foamDotFile''.  For this example, the sowfa version 2.0 based on OpenFOAM 2.1 and gcc called ''2.0-OF2.1-gcc'', it would do the following

<code>
    FOAM_INST_DIR=/opt/shared/openfoam/2.1.1-gcc
    WM_PROJECT_USER_DIR=$WORKDIR/sowfa/2.0-OF2.1-gcc
    source ${FOAM_INST_DIR}/etc/bashrc
</code>

You can check your VALET package by using

<code>
vpkg_versions <package>
vpkg_info <package>
</code>

==== Use VALET to setup your OpenFOAM application and build it ====

If you have correctly created and/or edited your VALET package for your OpenFOAM application package and version, then simply use the ''vpkg_require'' with the appropriate OpenFOAM application package and version followed by using the provided ''make'' to build the application.

For our sowfa version 2.0 based on OpenFOAM 2.1 and gcc example, we would use

<code>
    vpkg_require sowfa/2.0-OF2.1-gcc
    cd $WM_PROJECT_USER_DIR
    Allwmake
</code>