View source for Sig Turbomachinery Feature MixingPlane Interface OpenFOAM-1.6-ext

{{VersionInfo}}{{Version1.6-ext}}
= The mixingPlane interface for OpenFOAM-1.6-ext =

== Authors ==
* Martin Beaudoin, Hydro-Québec
* Hrv Jasak, Wikki Ltd.

== Description ==
The mixingPlane interface is implementing the interpolation of face data between two primitivePatches using mixing plane averaging.

The mixingPlane interface is a new addition to the OpenFOAM simulation toolbox. For turbomachinery simulation, the mixingPlane is essentially a 
circumferential averaging interface. For steady-state simulations in hydroturbines, it is common to use a mixingPlane 
interface between a guide vane passage and a runner passage, or between a runner passage and a full draft tube 
geometry. 

The main component of the mixingPlane interface is a circumferential averaging interpolator that computes and 
transfers average field values across the upstream and downstream patches that make up the mixingPlane. The 
interpolator is constructed using an intermediary cylindrical patch surface made of a stack of 360 degree  ribbons shared 
between two specially crafted GGI interfaces. 

Special care has been taken for the discretization of the cylindrical 
ribbon patch in order to appropriately interpolate both the coarse and fine regions of the upstream and downstream 
patches from the mixingPlane interface. A discretization profile is constructed based on the 2D upstream and 
downstream patch point distribution in cylindrical space. This 2D profile will then serve as the discretization control 
curve for generating the intermediary 360 degree ribbons patch. More information about the actual implementation details 
of the mixingPlane interface for OpenFOAM will be provided in upcoming publications.

== References ==
    OpenFOAM TURBO TOOLS: FROM GENERAL PURPOSE CFD TO TURBOMACHINERY SIMULATIONS 
    H. Jasak, M. Beaudoin, Proceedings of ASME-JSME-KSME Joint Fluids
    Engineering Conference 2011, AJK2011-FED, July 24-29, 2011, Hamamatsu,
    Shizuoka, JAPAN 

    Steady-state capabilities for hydroturbines with OpenFOAM,
    M. Page, M. Beaudoin, A.-M. Giroux, Internationnal Journal of Fluid
    Machinery and Systems, 4(1):160–170, Jan-Mar 2011.

    Development of a General Grid Interface for Turbomachinery simulations with
    OpenFOAM, M. Beaudoin, H. Jasak, Open Source CFD International Conference,
    December 2008 


== Availability of the source code, Downloading and Compiling==
===Availability of the mixingPlane_RC1 version of the source code for OpenFOAM-1.6-ext===
The mixingPlane interface is currently being developed for the version OpenFOAM-1.6-ext, available on openfoam-extend 

http://www.extend-project.de/

http://sourceforge.net/projects/openfoam-extend/

===How to download the source code===
Here is a quick recipe for downloading the  OpenFOAM-1.6-ext source code from the openfoam-extend git repository, and switching to the mixingPlane_RC1 branch

 mkdir ~/OpenFOAM                                                                                     # if you are starting from  scratch
 cd ~/OpenFOAM                                                                                        # 
 git clone git://git.code.sf.net/p/openfoam-extend/OpenFOAM-1.6-ext openfoam-extend-OpenFOAM-1.6-ext # cloning the git repo for OpenFOAM-1.6-ext
 cd ~/OpenFOAM/OpenFOAM-1.6-ext                                                                       # 
 git branch                                                                                           # Should say : "* master"
 git branch --track mixingPlane_RC1 origin/mixingPlane_RC1                                            # creating a local tracking branch for the remote branch origin/mixingPlane_RC1
 git checkout mixingPlane_RC1                                                                         # switch to your local mixingPlane_RC1 branch
 git branch                                                                                           # Should say : "* mixingPlane_RC1"

From here, it is best to recompile everything, including the ThirdParty packages.  New ThirdParty packages are utilized for the mixingPlane_RC1 branch.  The version of a ThirdParty package may also differ from the master branch

====Installing the source code alongside your main installation of OpenFOAM-1.6-ext====
It is always a good idea to put the source code for this version under a separate directory, like "$HOME/OpenFOAM/OpenFOAM-1.6-ext_mixingPlane_RC1". This way, you can keep tracking the main development branch from OpenFOAM-1.6-ext, without any risk of unwanted modifications to your main installation.

Here is the list of commands to install the source code of the mixingPlane_RC1 branch alongside your main installation of OpenFOAM-1.6-ext

 cd $HOME/OpenFOAM/
 git clone git://git.code.sf.net/p/openfoam-extend/OpenFOAM-1.6-ext OpenFOAM-1.6-ext_mixingPlane_RC1
 cd OpenFOAM-1.6-ext_mixingPlane_RC1
 git branch --track mixingPlane_RC1 origin/mixingPlane_RC1      
 git checkout mixingPlane_RC1   

Now, that the source code is properly downloaded, and we have switched to a local tracking branch for "mixingPlane_RC1", you need to modify the main configuration file for this new version that will be called "1.6-ext_mixingPlane_RC1".
For this, we need to modify the main configuration file ./etc/bashrc (or ./etc/cshrc). 

It is not a good idea to modify directly either of those files because any modifications to the "upstream" versions of those files from the git repository might come in conflict with your local modifications. So here is a pretty safe solution where you will simply create a new file called ./etc/bashrc.mixingPlane_RC1 (or /etc/cshrc.mixingPlane_RC1), and source this new file instead. Here, we will show the instructions for the "bashrc" version; the "cshrc" version is left as an exercise... :)

 cd $HOME/OpenFOAM/OpenFOAM-1.6-ext_mixingPlane_RC1/etc
 cp ./bashrc ./bashrc.mixingPlane_RC1

Next, we need to change the environment variable WM_PROJECT_VERSION from "1.-6-ext" to "1.6-ext_mixingPlane_RC1". This environment variable is defined in the file "./bashrc.mixingPlane_RC1"   

One can use his preferred text editor (emacs what else?) to make this modification, or you can also use this one-liner:
                                          
  sed -i.old 's/export WM_PROJECT_VERSION=1.6-ext/export WM_PROJECT_VERSION=1.6-ext_mixingPlane_RC1/g' ./bashrc.mixingPlane_RC1


That's it, you are now ready to activate your environment for this new version of OpenFOAM-1.6_ext, one that will coexist nicely alongside your main 1.6-ext installation. 

 . $HOME/OpenFOAM/OpenFOAM-1.6-ext_mixingPlane_RC1/etc/bashrc.mixingPlane_RC1
 cd $HOME/OpenFOAM/OpenFOAM-1.6-ext_mixingPlane_RC1/ThirdParty
 ./AllMake
 etc, etc


Other modifications might be in order for adapting this new installation to your local hardware or operating system, but those would be the same modifications as for your main installation of OpenFOAM-1.6-ext.

Either source code installation can also be kept up-to-date using the command "git pull" under their respective installation directories.

In order to easily activate one installation or the other, one could create aliases like these:

 alias of1.6-ext='. $HOME/OpenFOAM/OpenFOAM-1.6-ext/etc/bashrc'
 alias of1.6-ext_mixp='. $HOME/OpenFOAM/OpenFOAM-1.6-ext_mixingPlane_RC1/etc/bashrc.mixingPlane_RC1'

Another option for users of the command "module" is to use the newly available command "pyFoamCreateModuleFile.py" from PyFoam version 0.5.7 in order to create specific module files for either versions of OpenFOAM-1.6-ext. 

More information about the Environment Modules Project  can be found here : http://modules.sourceforge.net/

===How to update the source code===
Since the source code for this branch is still evolving, it is a good idea to update your local copy of the mixingPlane_RC1 source code on a regular basis.

Here are the commands to do just this:

 cd ~/OpenFOAM/OpenFOAM-1.6-ext  #
 git checkout mixingPlane_RC1    # switch to the local mixingPlane_RC1 branch
 git pull                        # Since our local mixingPlane_RC1 branch is tracking the remote branch, 'git pull' will update your local branch with the latest updates

And then recompile. Don't forget to check the recompilation of the ThirdParty packages as well, just in case some new stuff was added.

===How to compile the source code===
Compiling the source code for the mixingPlane_RC1 branch is no different than compiling the source code for OpenFOAM-1.6-ext. There is a lot of information out there on how to do this. The OpenFOAM Forums on CFD-Online is a good source of information. 

Here are the basic steps.

 cd ~/OpenFOAM/OpenFOAM-1.6-ext  
 git branch                         # Make sure the mixingPlane_RC1 branch is the active/current branch. 
                                    # If not, "git checkout mixingPlane_RC1".

 cd ~/OpenFOAM/OpenFOAM-1.6-ext/etc  
 < possibly some editing here >     # Make possible adjustments to the prefs.sh or prefs.csh files. 
                                    # Tweaking the bashrc or cshrc file might be necessary too depending on your platform
 . ./bashrc                         # (or source ./cshrc).  Sourcing your OpenFOAM environment

 cd ~/OpenFOAM/OpenFOAM-1.6-ext/ThirdParty  # Always compile the ThirdParty packages first
 ./Allmake

 cd ~/OpenFOAM/OpenFOAM-1.6-ext/  # Compile OpenFOAM-1.6-ext
 ./Allwmake

Hopefully, you are done.

== Current limitations ==
The development of the mixingPlane interface for OpenFOAM is still a work in progress at Hydro-Québec. Still, it was decided to publish a first "release candidate version" in 2012 in order to share the source code with collaborators and the community at large, and to stimulate some feedbacks and comments.
 
We are still working on improving this interface in order to use it with "industrial" grade meshes and large hydroturbine simulation problems. We will publish our improvements on a regular basis, so you have to expect some changes to the code (certainly), to the dictionaries syntax (possibly), and to the documentation (obviously) pertaining to the mixingPlane interface. '''So this source code should still be considered as experimental'''.

'''As of January 2012, the limitations of the current mixingPlane implementation (mixingPlane_RC1) are:'''
*The circumferential average of the various fields are computed from the cell-center values of the cells located on each side of the mixingPlane interface. We are missing a proper interpolation algorithm in order to evaluate the fields correctly when in presence of meshes where the size of the cells on either side of the mixingPlane varies significantly. The solution is known, but not implemented yet. We are actively working in order to fix this.  In the meantime, this is a limitation that can be overcome by imposing constraints on your mesh generator. The size of the first layer of cells on the upstream and downstream side of the interface should be mostly homogeneous. This does not mean the size of the cells should be the same for BOTH the upstream and downstream side. They have to be homogenous on the upstream side, and homogenous on the upstream side.
*The interface is not fully parallelized yet. In order to run mixingPlane cases in parallel, just make sure the interface and the cells on each side of the interface are located on the same processor.
* ''First make it run, then make it run fast''. We are at the "first make it run" stage of the development. So performance has not been addressed yet. We are using the GGI interface as an internal component for this new development, so the performance of the mixingPlane will always be closely linked to the performance of the GGI interface.

== Examples of dictionaries configuration ==

*constant/polyMesh/boundary
 Todo

*field value dictionaries in the time directories
 Todo

== Specification of mixingPlane reference frame==
Todo

== Specification of the mixingPlane discretization profile ==
Todo

== Running the mixingPlane in parallel ==
Todo

== The mixingPlaneCheck functionObject ==
Todo

== The checkMixingPlane utility program ==
Todo

== Tutorials ==
* Simplistic examples
* The ERCOFTAC conical diffuser
* The ERCOFTAC centrifugal pump
* Simple rotor-stator examples


== Test harness ==
Todo

[[Category:Incomplete pages]]