BLUECAPE LDA
blueCFD documentation
Core
V2.3-1 – March 2014
BLUECAPE LDA
blueCFD documentation
Core
V2.3-1 – March 2014 blueCFD is a registered Trademark of blueCAPE Lda. OpenFOAM is a registered Trademark of OpenFOAM Foundation. All other trademarks are registered by their respective owners. Neither blueCAPE nor blueCFD are either endorsed or affiliated with any entity whatsoever.
blueCFD-Core 2.3
Table of Contents
Introduction .................................................................................................................................2 1. Installation ..............................................................................................................................3 1.1. Preparations before installing .......................................................................................4 1.2. How to install ................................................................................................................5 1.3. Advanced installation options .....................................................................................14 2. Getting Started .....................................................................................................................15 2.1. Start Menu...................................................................................................................16 2.2. MSys Terminal.............................................................................................................20 2.3. Windows Command Line ............................................................................................23 2.4. Working with OpenFOAM cases.................................................................................26 3. Running in Parallel...............................................................................................................30 3.1. Available MPI Toolboxes .............................................................................................31 3.1.1. MS-MPI...............................................................................................................32 3.1.2. Open-MPI ...........................................................................................................38 3.2. Configure Windows Firewall .......................................................................................44 3.2.1. Configure Automatically the Windows 7 Firewall ...............................................45 3.2.2. Configure Manually the Windows Firewall .........................................................47 3.3. Changing MPI options ................................................................................................51 3.4. Troubleshooting ...........................................................................................................52 4. Building from Source Code..................................................................................................53 4.1. Using Run-time Code Compilation .............................................................................54 4.2. Building Custom Code ................................................................................................55 4.3. Compiling OpenFOAM ................................................................................................57 4.3.1. Understanding the shell environment ................................................................59 5. Third-Party Software ............................................................................................................62 5.1. Notepad2 .....................................................................................................................63 5.2. ParaView .....................................................................................................................65 5.2.1. Using ParaView ..................................................................................................66 5.2.2. Using ParaView Server ......................................................................................67 5.2.3. Miscellaneous notes...........................................................................................68 5.3. Blender ........................................................................................................................69 5.4. enGrid ..........................................................................................................................70 5.5. SwiftBlock and SwiftSnap ...........................................................................................72 5.6. Discretizer....................................................................................................................73 5.6.1. Using Discretizer ................................................................................................74 5.6.2. Using Discretizer::Setup .....................................................................................76 5.6.3. Updating Discretizer ...........................................................................................77 5.7. Gnuplot ........................................................................................................................78 5.8. Python .........................................................................................................................79 5.9. GDB .............................................................................................................................80 5.10. CMake .......................................................................................................................81 5.11. Git ..............................................................................................................................82
1 | Page
©blueCAPE
blueCFD-Core 2.3
Introduction
This document provides information on the use of blueCFD-Core. At blueCAPE, we have put in a lot of effort to make this software product and service and are keen to better serve and assist you in exploiting the many advantages of Computational Fluid Dynamics. blueCFD-Core is a complete port of OpenFOAM for Windows and is unique in its kind. We strive to make all of the original solvers and utilities available in the Windows operating system, thereby allowing an experience entirely similar between Linux and Windows. This also includes the ability to compile all of the ported OpenFOAM source code directly in Windows. In addition, we try to bring as much open-source software from the OpenFOAM community to the Windows platform, integrated into blueCFD-Core, therefore a Windows user can thus feel to be a member of full right in the OpenFOAM community. This document is part of blueCFD-Core, which aims to bridge the software provided in it and the existing public documentation for OpenFOAM and related software. Therefore, this document is divided into the following chapters: • 1. Installation - Here is explained how to install blueCFD-Core. • 2. Getting Started - Here is explained how to start using the command lines and where to start studying OpenFOAM. • 3. Running in Parallel - Here is explained how to use OpenFOAM with multiple processors in a single machine. • 4. Building from Source Code - Here is explained how to build OpenFOAM based software from source code. • 5. Third-Party Software - Here is explained where to learn about how to use each one of the provided software applications for using with OpenFOAM.
2 | Page
blueCFD-Core 2.3
1. Installation
As of blueCFD-Core 2.3-1, the installation procedure has been simplified. Nonetheless, there are some preliminary steps that may be necessary, depending on the installation procedure you choose to follow: • If you wish to install the code documentation (which provides an deep insight into the source code), then please first read the section Preparations before installing • To understand how the installation process works, then please read the section How to install
3 | Page
©blueCAPE
blueCFD-Core 2.3
1.1. Preparations before installing
Note: This section is only applicable for those who wish to also install the code documentation and have a firewall constraining downloads. The current installer only relies on an optional downloadable file, which is (or will be) placed inside the folder "blueCFD-Core-downloads", next to the installer:
This folder is usually only created when the installer is launched, but it can be created manually, prior to running the installer. If you have a restrictive firewall and wish to install the code documentation, then please download the package from the link provided from one of the following locations: • In the blueCFD-Core download area at bluecape.com.pt, there is a link for the "Code Documentation" package. • Or run the installer once, so that it will create the file "downloads_list.txt" inside the folder "blueCFD-Core-downloads", which contains the link to the file that needs to be downloaded:
Place the downloaded file inside the folder "blueCFD-Core-downloads" and proceed to the next section: How to install
4 | Page
blueCFD-Core 2.3
1.2. How to install 1. Once the installer starts, it will show the following window:
2. Click on the Next button and it will show the window with the license information:
5 | Page
©blueCAPE
blueCFD-Core 2.3
3. Once you've accepted the license agreement, click on the Next button and it will ask where blueCFD-Core should be installed:
4. Note: if you're planning on doing advanced software development with OpenFOAM based source code, such as compiling the Debug or Single Precision 6 | Page
blueCFD-Core 2.3 versions of OpenFOAM on Windows, then it's advisable to install blueCFD-Core in your own user folder. For more information, check the section: Advanced installation options 5. Once the location is chosen, click on the Next button and it will ask what type of installation to perform:
6. The types of installation are essentially: a. "Typical installation" - To install everything, except for the code documentation. b. "Full installation" - To install everything, including the code documentation. The advantage here is that this makes it easier to find more details about certain features that OpenFOAM has got, such as Boundary Conditions and Function Objects, which are not documented in the User Guide. c. "Custom installation" - Where you can choose which applications and features you want to install, as exemplified here:
7 | Page
©blueCAPE
blueCFD-Core 2.3
7. Once the choices have been made, click on the Next button, which will allow choosing the Start Menu group where the blueCFD-Core shortcuts should be placed:
8. 8 | Page
blueCFD-Core 2.3 After choosing the group name, click on the Next button, which lead to the window with the following options:
a. The desktop icon is useful specially on Windows 8 and 8.1, due to the nonexistence of a Start Menu. Without this icon, it could get very complicated to use blueCFD-Core on those versions of Windows. b. The option to "Add Notepad2 to the right-click on any file in Windows Explorer" is very useful for editing the OpenFOAM case files. c. The option to "enable write permissions" is necessary and advisable when the user currently installing blueCFD-Core is able to perform administrative installations. When this occurs, the installation will likely be made in a restrictive access location, such as "C:\Program Files". This is where this option to "enable write permissions" comes in, namely to give the ability to write in the main user folders "ofuser-2.3", "msys\home\ofuser" and "msys \etc", which without this option, will disrupt the conventional installation process. 9. Once the choices have been made, click on the Next button and it will show the final window before the installation begins:
9 | Page
©blueCAPE
blueCFD-Core 2.3
10. Clicking on the Next button will proceed with the installation. 11. If the Code Documentation was selected to be installed, then it will attempt to download the necessary package, therefore showing this window:
12. 10 | Page
blueCFD-Core 2.3 Once the download is complete (if it was needed), then it will proceed to install all of the selected features:
13. The progress bar will go forward with the advancement of the installation process. When it reaches the end of the files to be installed, it will take care of wrapping up the installation, by running the external installers and unpack the Code Documentation package, if necessary. This will reset the progress bar for this second progress stage:
11 | Page
©blueCAPE
blueCFD-Core 2.3
14. Note: one of the possible steps in this second progress stage is to install the Microsoft 2010 Runtime, which will ask you to follow it's own installation steps. 15. Once the installation is complete, it will show the following window:
16. 12 | Page
blueCFD-Core 2.3 There, you can choose to begin reading the blueCFD-Core User Guide and/or to see our Twitter page to get the latest news regarding blueCAPE and blueCFD. 17. Once you click in the Finish button, blueCFD-Core is then installed with the chosen features!
13 | Page
©blueCAPE
blueCFD-Core 2.3
1.3. Advanced installation options
The blueCFD-Core installer has a hidden feature that allows a user with administrative powers to perform an installation for personal use only. To perform this, launch the installer with the option "/SINGLEUSER=1", from a Windows command line: blueCFD-Core-2.3-1-win64-setup.exe /SINGLEUSER=1
In addition, the installer for blueCFD-Core was generated using Inno Setup, therefore all other command line options are also available, which are documented on the official website for Inno Setup: Inno Setup Command Line Parameters
14 | Page
blueCFD-Core 2.3
2. Getting Started
This chapter aims to explain how to get started with using OpenFOAM, as it is provided in blueCFD-Core. The 3 major topics that will be addressed on this chapter are split into the following sections: • 2.1. Start Menu - In this section will be given an overall view of how to access the software and documentation provided in blueCFD-Core. • 2.2. MSys Terminal - In this section is explained what is the MSys terminal and how to get around within the MSys terminal. • 2.3. Windows Command Line - In this section is explained how to get around within the Windows Command Line. • 2.4. Working with OpenFOAM cases - In this section is given a brief explanation on how to work with OpenFOAM cases.
15 | Page
©blueCAPE
blueCFD-Core 2.3
2.1. Start Menu
The Start Menu, as shown below on the left, is the conventional way to access installed applications in Windows, at least until Windows 8 appeared. From the "All Programs" menu item, it's then possible to list the contents of the blueCFD-Core group menu, as shown below on the right, displaying most of the shortcuts and links provided by blueCFD-Core.
On Windows 8, given the replacement of the Start Menu for a Start Screen, blueCFDCore provides a shortcut in your Windows Desktop (optional during installation) to access the same shortcuts that are provided in the previous picture on the right. The shortcut in the Windows Desktop should look something like this:
Opening that shortcut (double-click on it or select then press the Enter key), which show a new Windows Explorer window a list similar to the following image:
16 | Page
blueCFD-Core 2.3
Therefore, taking into account the items shown on these lists, here is a description and location of some of the most important ones: • Browse blueCFD-Core folder - This shortcut leads to the contents of the folder where blueCFD-Core was installed. • This is useful for getting around inside the installation, as the user files are placed next to OpenFOAM's own installation and because OpenFOAM has a hands-on approach to CFD. • Install your blueCFD-Core in a Portable drive or folder - This is a convenient application for copying the whole blueCFD-Core installation to a portable drive. • MSys terminal - This is the primary command based interface with OpenFOAM, as explained in section 2.2. MSys Terminal. • Windows Command Line - This is the alternative command based interface with OpenFOAM, as explained in section 2.3. Windows Command Line. • Documentation - This folder holds shortcuts to all of the important documentation relevant to using blueCFD-Core, OpenFOAM and all other 3rd party software provided with blueCFD-Core. If it feels that there is anything missing, then check the folder Web. The most important documents are: • blueCFD-Core User Guide - This document you're currently reading. • OpenFOAM User Guide - As the title says, this is one of the most important documents for learning how to use OpenFOAM. • OpenFOAM Programmers Guide - This is a complementing document to the OpenFOAM User Guide, also developed by OpenCFD, but not fully maintained by them. • Local OpenFOAM 2.3 Code Documentation - This is only available when the Code Documentation is installed (see chapter 1. Installation). • This is useful for looking up information that is not provided in the OpenFOAM User Guide. • It requires ParaView 4.1.0 to also be installed inside blueCFD-Core. • 17 | Page
©blueCAPE
blueCFD-Core 2.3 GUI - This folder provides shortcuts for several Graphical User Interfaces, where all of them are open-source. In order of usability: • Notepad2 - This is a simple, yet very advanced, text editor. It is provided with blueCFD-Core, because it acts as a good replacement to the default Windows Notepad application, specially due to the limitations in Notepad to properly open OpenFOAM files. For more information, see section 5.1. Notepad2. • ParaView - This is the standard post-processing application used for processing the results generated with OpenFOAM. For more information, see section 5.2. ParaView. • Blender - This is a well known 3D modelling application, although mostly oriented for the creation of computer animated movies. It's provided with blueCFD-Core also due to Blender's powerful add-on mechanism, for which it's also included: • enGrid's import and export scripts - see section 5.4. enGrid. • SwiftBlock and SwiftSnap - see section 5.5. SwiftBlock and SwiftSnap. • enGrid - This is a mesh generation software with CFD applications in mind. It first imports a surface mesh, can generate/improve said surface mesh and only then will it generate the volume mesh. It uses Netgen for generating tetrahedral meshes, but can then perform an advanced export to a polyhedral mesh. For more information see 5.4. enGrid. • Discretizer and Discretizer Setup - These two are part of the same software application - see section 5.6. Discretizer - where: • Discretizer is for manually drawing meshes. • Discretizer Setup is a pre-processor, i.e. helps prepare cases. • Gnuplot - This is an advanced application for plotting data, further documented in section 5.7. Gnuplot. It comes in two flavors: • The GUI, which provides a mouse assisted approach to creating graphs. • The Shell, which provides a strict command line approach to creating graphs. • Python Shell - A command line interface for using the programming language Python. It's currently provided as a complement to ParaView's Python capabilities, but it can also be used with PyFoam, SciPy, etc... For more information, see section 5.8. Python. • Python IDLE - A graphical user interface for Python, making it easier to write and test Python source code. • CMake (cmake-gui) - A graphical user interface for building software that rely in CMake, which is a cross-platform build system. For more information see section 5.10. CMake. • Licenses - In this folder is a list of shortcuts to the files that indicate the licenses of each software application provided. Because even though all of the provided software is open-source, many of them have their own licenses, respective to the distribution of source code and binaries and the software themselves use. 18 | Page
blueCFD-Core 2.3 • Settings - In this folder are folders that have shortcuts for configuring the following features: • MPI mode - Inside this folder are shortcuts for defining the default MPI toolbox to be used for running OpenFOAM in parallel. Simply (double) click on any one of them and this will be the new default for the next time you start an MSys terminal and/or Windows Command Line. For more information about each toolbox, see chapter 3. Running in Parallel. • MSys console - Inside this folder are shortcuts for defining the default console interface to be used in MSys. The default console is MINTTY, as it is the most flexible console interface. Feel free to try out the other console modes, because: • RXVT is similar to MINTTY, but not as powerful and has some compatibility issues with an undetermined number of Windows installations. • SH is similar to the Windows Command Line, as it's the most basic of the console interfaces and should be compatible with any Windows installation. • Un-install - In this folder are links to the applications provided with blueCFD-Core that can be uninstalled. Most likely the only link for uninstalling blueCFD-Core is provided there. • Web - In this folder are all links to online websites which provide information for the software provided with blueCFD-Core. This is where most of the remaining documentation can be found.
19 | Page
©blueCAPE
blueCFD-Core 2.3
2.2. MSys Terminal
The MSys terminal is the primary interface for interacting with OpenFOAM. This is because MSys provides a terminal-like interface similar to the ones usually seen in Linux/Unix, therefore giving a similar experience in using OpenFOAM. Here's an example of what the MSys terminal looks like:
To start the MSys terminal, see section 2.1. Start Menu. Once launched, it will take a little while (3-5 seconds) to show you a similar window to the one above, where it will take another few seconds to prepare shell environment to use OpenFOAM, hence the message: Setting environment for mingw-w64 Double Precision, using MSMPI2012 please wait...
If there is more than one architecture of OpenFOAM installed, it should show a list of options, e.g.: -------------- Setting up OpenFOAM variables --------------- Current MPI chosen for parallel operations: MSMPI2012 Choose one option for selecting the build architecture: 1
- mingw-w32 Single Precision
(of23-32S)
3
- mingw-w64 Double Precision
(of23-64)
2
- mingw-w32 Double Precision
(of23-32)
Choose 1, 2 or 3 (any other for none) then press Enter:
If this is the case, you should choose one of them, but you can press any other key for skipping the activation of any architecture. Then press the Enter key to continue. Depending on your option, one of the following scenarios will occur: 20 | Page
blueCFD-Core 2.3 • If you chose one of the installed architectures, it will show something like this: Setting environment for mingw-w64 Double Precision - please wait... Environment is now ready.
It will take a few seconds to start the environment, due to the complexity of scripts that OpenFOAM has got. When the second line appears, you are ready to continue. • If you chose neither one, you can activate one of the environments on demand, as shown between parenthesis. For example, to activate the 64bit double precision version, you can run: of23-64
It will take the same amount of time as when launching from the initial menu, but it will not show you the messages in the previous scenario. Next we will follow the initial steps of the official OpenFOAM User Guide. The usual work folder should be at ~/blueCFD/ofuser-2.3/. Run the following commands: cd blueCFD/ofuser-2.1/ mkdir run
This will create the run folder, for running your OpenFOAM cases. In Windows, this folder will be at blueCFD-Core-2.3\ofuser-2.3\run. You can now make a full copy of the tutorials if you want to run them all! To make a full copy, do: cd run
cp -r $FOAM_TUTORIALS/ tutorials
Now you can follow the tutorial instructions available at the OpenFOAM User Guide (see section 2.1. Start Menu), starting page U-17. You should be able to run all of the commands available there. Nonetheless, first see the section 2.4. Working with OpenFOAM cases to get a better idea on how to interact with OpenFOAM's cases. Things to keep in mind: • Be advised that a few of the scripts available under MSys, have not been subject to a thorough testing process. This means that some problems may appear. If that happens, please report back to blueCAPE. • The command foamCleanTutorials helps clean up tutorial cases, either local case or multiple cases. • The command foamRunTutorials helps to run tutorial cases, either local case or multiple cases. • Given that the MSys terminal acts nearly identically to a terminal/console in Linux, it's highly advisable to study more on how to use the shell for these interfaces. 21 | Page
©blueCAPE
blueCFD-Core 2.3
•
•
• •
For more information, here is a good online tutorial: http://linuxcommand.org/ learning_the_shell.php The text editors that can be used from the command line are: • vi • notepad2 • nano - this is an alias to running Notepad2 MSys terminal has auto-completion! Simply type part of the command you are looking for, press the Tab key and it will show the possibilities or fill in the missing text. For example, type foam then press the Tab key and script names and executables will be shown. For running parallel cases (multi-core and multi-machine), see the chapter 3. Running in Parallel. For more help, keep reading the OpenFOAM User Guide and/or Programmers Guide (see section 2.1. Start Menu) and/or see check the links inside the Web folder (see section 2.1. Start Menu).
22 | Page
blueCFD-Core 2.3
2.3. Windows Command Line
The Windows Command Line (WCL) is the alternative interface for interacting with OpenFOAM. This is because the WCL is more limited than using the MSys terminal, given that most of OpenFOAM's auxiliary scripts are meant to be used in a shell environment. Nonetheless, it's still possible to use OpenFOAM from WCL, specially since some of shell commands can still be used, such as bash, grep and sed. Here is an example of what a WCL looks like:
To start the WCL, see section 2.1. Start Menu or double-click on the DOS_Mode.bat file provided in the base folder of blueCFD-Core. Once launched, it will very quick to show a window similar to the one shown above. When there is only one installed architecture, it will activate it automatically. When there is more than one architecture installed, a menu with the installed options will appear. For example, a full installation with Open-MPI selected by default, provides the following options: -------------- Setting up OpenFOAM variables --------------- Current MPI chosen for parallel operations: OPENMPI
Choose one option for selecting the build architecture: 1 - mingw-w32 Single Precision 2 - mingw-w32 Double Precision 3 - mingw-w64 Double Precision Choose one (press the respective key number):[1,2,3]?
You have to choose one of them. When this is done, you will be given the prompt. Should be something like: C:\Program Files\blueCFD-2.3>
23 | Page
©blueCAPE
blueCFD-Core 2.3 The main differences versus the MSys terminal are: • With MSys you can execute the scripts that come with the original OpenFOAM directly. • If MSys is installed, then with CMD you can run those scripts by prepending the sh command. For example: sh foamJob
This is only necessary for shell scripts only (the ones in OpenFOAM's bin folder and such as Allrun). • With the CMD you get a bit more speed in displaying results on screen. Next we will follow the initial steps of the official OpenFOAM User Guide. The usual work folder should be at blueCFD-Core-2.3\ofuser-2.3. Run the following commands: cd ofuser-2.3 mkdir run
This will create the run folder, for running your OpenFOAM cases. In Windows, this folder will be at blueCFD-Core-2.3\ofuser-2.3\run. You can now make a full copy of the tutorials if you want to run them all! To make a full copy, do: cd run
xcopy /S /E %FOAM_TUTORIALS%\*.* tutorials\
Now you can follow the tutorial instructions available at the OpenFOAM User Guide (see section 2.1. Start Menu), starting page U-17. You should be able to run most of the commands available there. Nonetheless, first see the section 2.4. Working with OpenFOAM cases to get a better idea on how to interact with OpenFOAM's cases. Things to keep in mind: • In WCL, only a few batch files for WCL are made available: • paraFoam.bat - will launch ParaView to show your local case. It does not provide the same options as the Linux version of paraFoam script. • gompi.bat - type: gompi
And it will launch the application using the selected MPI during start-up. For more information about this, please read the chapter 3. Running in Parallel. • As mentioned above, for running parallel cases (multi-core and multi-machine), please read the chapter 3. Running in Parallel. • The text editor that can be used from the command line is notepad2. • 24 | Page
blueCFD-Core 2.3 WCL has limited auto-completion... it only auto-completes local file and folder names; in other words, it will only complete the path that you tell it to look at. Simply type part of the command you are looking for and for each time you press the Tab key, it will cycle through the names that fit the description. • For more help, keep reading the OpenFOAM User Guide and/or Programmers Guide (see section 2.1. Start Menu) and/or see check the links inside the Web folder (see section 2.1. Start Menu).
25 | Page
©blueCAPE
blueCFD-Core 2.3
2.4. Working with OpenFOAM cases
OpenFOAM has been created to work with text files, as it does not provide any Graphical User Interface for interacting with it. Which means that almost all files necessary for preparing a case in OpenFOAM require a text editor. Therefore, this section aims to give an introductory explanation on how to work with an OpenFOAM case. First of all, always keep at least one terminal open at all times at the base folder of your case. We'll use as an example the folder for the first tutorial taught in the OpenFOAM User Guide:
Now, if you run this command: explorer .
as exemplified here:
26 | Page
blueCFD-Core 2.3
it will show a Windows Explorer window, displaying the content of the folder:
If you go into the folder "0", then right click on the file "p" and choose the entry "Open with Notepad2", it will open the file for editing:
27 | Page
©blueCAPE
blueCFD-Core 2.3
Keep in mind to not use the normal Notepad application that comes with Windows, as it is not able to open these files properly, as exemplified here:
28 | Page
blueCFD-Core 2.3
Once you've made the changes, be sure to save the file. Closing the text editor is not obligatory, as it can be useful later on. Going back to the terminal, you can run the commands for generating the mesh and then for running the solver, such as for this case: blockMesh icoFoam
It will should a considerable amount of information, so you might want to make sure that said information is kept inside log files, therefore running the commands like this: blockMesh > log.blockMesh icoFoam > log.icoFoam
Once the applications have finished running, you have a look into the files "log.blockMesh" and "log.icoFoam", for example by running one of the following commands: nano log.icoFoam
notepad2 log.icoFoam
If you wish to continue using the command line, even after opening the text file, then append an ampersand to the command, like this: nano log.icoFoam &
notepad2 log.icoFoam &
And this is essentially the objective of this section. If you prefer, you may wish to download and install Notepad++, as it provides a tabbed view, therefore giving you the ability to open all of the files you want in a single window.
29 | Page
©blueCAPE
blueCFD-Core 2.3
3. Running in Parallel
On this article will be described the basics of using OpenFOAM in parallel, along with all of the miscellaneous details required for running it on Windows. The article has the following chapters: • • • •
3.1. Available MPI Toolboxes 3.2. Configure Windows Firewall 3.3. Changing MPI options 3.4. Troubleshooting
30 | Page
blueCFD-Core 2.3
3.1. Available MPI Toolboxes
blueCFD-Core comes prepared to work with the several MPI toolboxes and these are described in more detail on the following articles: • 3.1.1. MS-MPI • 3.1.2. Open-MPI For those who are familiar with previous versions of blueCFD-Core, might notice that the MPICH2 toolbox is no longer available by default. This is because the development of MPICH2 for Windows has been completely shifted to Microsoft's MS-MPI. Nonetheless, the building process for using MPICH2 1.4.1p1 is still available in the source code structure in the folders OpenFOAM-2.3 and ThirdParty-2.3.
31 | Page
©blueCAPE
blueCFD-Core 2.3
3.1.1. MS-MPI
This subsection aims to provide the essential reference information on how to run OpenFOAM applications in parallel using MS-MPI. The main emphasis is on running with multiple cores in a single machine.
Introduction
As mentioned in the introductory text in the section 3.1. Available MPI Toolboxes, MSMPI is based on MPICH2 and has taken over development as of MPICH2 1.5 (for more information about this, see Microsoft MPI online). In addition, blueCFD-Core provides 2 versions of MS-MPI: • MS-MPI for Windows Server 2008R2 • MS-MPI for Windows Server 2012 The following overview is valid for each computer where you installed blueCFD-Core. Details to keep in mind: • blueCFD-Core comes with MS-MPI 2012 active by default. To switch MPI versions, see the Settings folder description in section 2.1. Start Menu. Then start a new WCL window or MSys terminal. • MS-MPI will not run in Windows XP or older. • Be advised that the installations should be done equally in the same path, or in a network shared drive. For example, all machines should use the same blueCFD path: C:\blueCFD-Core-2.3
• User accounts should be of the same name and password. Currently we haven't tested yet running with different user accounts. • If your Windows Firewall is active, see the section 3.2. Configure Windows Firewall. • It might be necessary to install MS-MPI globally on all machines, independently from blueCFD-Core. This might be necessary in some cases, so it's a trial-and-error effort. You can install MS-MPI globally by following these steps: a. Go to the Start Menu and choose the shortcut "Browse blueCFD-Core folder" (see section 2.1. Start Menu). b. Browse in Windows Explorer to the folder respective to the MS-MPI version: i. MS-MPI 2008R2: blueCFD-Core-2.3\ThirdParty-2.3\platforms \linuxmingw-w64\msmpi-2008R2
ii. MS-MPI 2012: blueCFD-Core-2.3\ThirdParty-2.3\platforms \linuxmingw-w64\msmpi-2012
c. Inside those folders you'll find the respective installer: i. MS-MPI 2008R2: MSMPI2008_mpi_x64.msi ii. MS-MPI 2012: MSMPI2012_mpi_x64.msi d. Double-click on it and follow the installation instructions. 32 | Page
blueCFD-Core 2.3 • In case you plan on deployment in a cluster, it's advisable to instead install the Windows HPC Pack: https://www.microsoft.com/hpc/
Run in a single machine with multiple cores
Unlike MPICH2, MS-MPI does not need SMPD to be launched manually when running with a single computer. Nor does it need to register the user password to be used by the MPI toolbox. To test if it's working, choose whether to run in WCL or MSys. Then, accordingly to the choice made: • From WCL: a. Go to the folder ofuser-2.3\pTestCase: cd ofuser-2.3\pTestCase
b. Then run: gompi Test-parallel
It will test communications between two instances of Test-parallel.exe. c. If successful, it should display something like this: C:\Program Files\blueCFD-Core-2.3\ofuser-2.3\pTestCase>mpiexec -n 2 -parallel
Test-parallel
/*---------------------------------------------------------------------------*\ | ========= | \\ |
/
|
\\
/
\\
|
/
\\/
F ield
O peration A nd
M anipulation
|
|
| OpenFOAM: The Open Source CFD Toolbox | Version: | Web: |
|
2.3
|
www.OpenFOAM.org
| |
\*---------------------------------------------------------------------------*/ /* |
Windows 32 and 64 bit porting by blueCAPE: http://www.bluecape.com.pt
Based on Windows porting (2.0.x v4) by Symscape: http://www.symscape.com
*\ |
\*---------------------------------------------------------------------------*/ Build
: 2.3-21131bcbd876
Date
: Jul 21 2010
Exec Time Host PID
Case
: Test-parallel.exe -parallel : 16:21:16
: THE_MACHINE : 712
: C:/Program Files/blueCFD-Core-2.3/ofuser-2.3/pTestCase
nProcs : 2 Slaves :
33 | Page
©blueCAPE
blueCFD-Core 2.3 1 (
THE_MACHINE.5024 )
Pstream initialized with: floatTransfer
: 0
commsType
: nonBlocking
nProcsSimpleSum
: 0
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * // Create time [1]
Starting transfers [1]
[1] slave sending to master 0
[1] slave receiving from master 0 [0]
Starting transfers [0]
[0] master receiving from slave 1 [0] (0 1 2)
[0] master sending to slave 1 End
[1] (0 1 2)
Finalising parallel run
• From MSys terminal: a. Go to the folder ofuser-2.3/pTestCase:
cd blueCFD/ofuser-2.3/pTestCase
b. Then run: foamJob -p -s Test-parallel
It will test communications between two instances of Test-parallel.exe. c. If successful, it should display something like this: ofuser@THE_MACHINE ~/OpenFOAM/ofuser-2.3/pTestCase $ foamJob -p -s Test-parallel Application : Test-parallel
34 | Page
blueCFD-Core 2.3 Parallel processing using MSMPI2012 with 2 processors
Executing: mpirun -np 2 /home/ofuser/blueCFD/ofuser-2.3/linuxmingw-w64DPOpt/bin/ Test-parallel
-parallel | tee log
/*---------------------------------------------------------------------------*\ | ========= | \\ |
/
|
\\
|
F ield
/
\\
|
/
O peration
\\/
A nd
M anipulation
|
| OpenFOAM: The Open Source CFD Toolbox | Version: | Web: |
|
2.3
|
www.OpenFOAM.org
| |
\*---------------------------------------------------------------------------*/ /* |
Windows 32 and 64 bit porting by blueCAPE: http://www.bluecape.com.pt
Based on Windows porting (2.0.x v4) by Symscape: http://www.symscape.com
*\ |
\*---------------------------------------------------------------------------*/ Build
: 2.3-21131bcbd876
Date
: Jul 21 2010
Exec Time
: 16:19:31
Host PID
: Test-parallel.exe -parallel
: THE_MACHINE
Case
: 1360
: C:/Program Files/blueCFD-Core-2.3/ofuser-2.3/pTestCase
nProcs : 2 Slaves : 1 (
THE_MACHINE.3560 )
Pstream initialized with: floatTransfer
: 0
commsType
: nonBlocking
nProcsSimpleSum
: 0
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * // Create time [0]
Starting transfers [0]
[0] master receiving from slave 1 [1]
Starting transfers [1]
35 | Page
©blueCAPE
blueCFD-Core 2.3 [1] slave sending to master 0[0] (0 1 2) [0] master sending to slave 1
[1] slave receiving from master 0 [1] (0 1 2) End
Finalising parallel run
Run in multiple machines in parallel
When running with multiple machines with MS-MPI, it's advisable to install the Windows HPC Pack: https://www.microsoft.com/hpc/ Nonetheless, it's possible to launch the applications in parallel in multiple machines, one can resort to the running SMPD as a daemon. This might make it possible to run smpd on the machines that you don't have administrative access (depends on the firewall). To do so, open either a WCL or a MSys terminal (without administrative powers) and run: smpd -p 12345 -d
Note: -p 12345 is optional and indicates that the port 12345 is to be used by the smpd daemon mode. This option is required only if there is already a system smpd running or if you are restricted to a specific port. You can then terminate it by pressing Ctrl+C. Before launching the application (solver or utility) in parallel with multiple machines, the premise is that all machines must be able to see the case folder, whether it's the same folder or a copy of the original folder. Therefore, you'll need to either: • Make a full copy of the case folder, after decomposing and place it in the same path on all machines. • Or share the case folder in the local network, along with mapping a drive letter to this folder. Beyond this, the default blueCFD-Core service does not support running in parallel with multiple machines. If you have this need, please contact blueCAPE for more information for this support.
Using Windows HPC 36 | Page
blueCFD-Core 2.3 This article will not cover in detail on how to use Windows HPC. Nonetheless, the good people at Symscape provide some short instructions on how to use the Windows HPC Job Scheduler (source). Those instructions have been adapted here for the blueCFD-Core working environment, specifically for launching simpleFoam from the architecture mingw-w64: job submit /jobname:simpleFoam-jobName /name:simpleFoam-taskName / numprocessors:16 /stdout:\\CRAY01\\stdout.txt /stderr:\
\CRAY01\\stderr.txt mpiexec -env WM_PROJECT_DIR \\CRAY01\
$(WM_PROJECT_DIR) -env MPI_BUFFER_SIZE 20000000 -env USERNAME ofuser -env
PATH \\CRAY01\$(WM_PROJECT_DIR)\platforms\linuxmingw-w64DPOpt\lib;\\CRAY01\ $(WM_PROJECT_DIR)\platforms\linuxmingw-w64DPOpt\lib\msmpi-2008R2 \\CRAY01\ $(WM_PROJECT_DIR)\platforms\linux64mingw-w64DPOpt\bin\simpleFoam -parallel -case \\CRAY01\
37 | Page
©blueCAPE
blueCFD-Core 2.3
3.1.2. Open-MPI
This subsection aims to provide the essential reference information on how to run OpenFOAM applications in parallel using Open-MPI. The main emphasis is on running with multiple cores in a single machine.
Introduction
The current version of Open-MPI provided with blueCFD-Core is Open-MPI 1.6.2. This support may be discontinued in the future, as further development on Open-MPI for Windows was dropped. The following overview is valid for each computer where you installed blueCFD-Core. Details to keep in mind: • blueCFD-Core comes with MS-MPI 2012 active by default. To switch MPI versions, see the Settings folder description in section 2.1. Start Menu. Then start a new WCL window or MSys terminal. • Be advised that the installations should be done equally in the same path, or in a network shared drive. For example, all machines should use the same blueCFD path: C:\blueCFD-Core-2.3
• User accounts should be of the same name and password. Currently we haven't tested yet running with different user accounts. • If your Windows Firewall is active, see the section 3.2. Configure Windows Firewall. • Currently documentation for using Open-MPI is a bit scarce. It's left to the reader to search for more information about this, although a good starting point is the OpenMPI FAQ: http://www.open-mpi.org/faq/
Run from MSys
There is a particular issue that should be kept in mind when using Open-MPI and MSys together: they actually can't work together! Nonetheless, with blueCFD-Core are provided 3 wrapper scripts that take care of the details for launching OpenFOAM solvers and utilities in parallel directly from an MSys terminal: • When using foamJob for launching a solver or utility in parallel, it will automatically call the openmpiJob script to launch the application separately from the MSys terminal. • When using the RunParallel function that the Allrun scripts use in the tutorial cases, it will call the script openmpiRunParallel for automatically launching the application separately from the MSys terminal. • 38 | Page
blueCFD-Core 2.3 If the user presses the key combination Ctrl+C for terminating the execution in parallel, then only the running script will terminate, but will not terminate the parallel applications. To terminate those applications, one must run openmpiKillJob to terminate those running parallel. Note: The 0 in the following two examples is a necessary argument for a yet-to-beimplemented functionality. Examples: a. If the run was launched with foamJob, then use the command: openmpiKillJob 0 log
b. If simpleFoam was launched with RunParallel (probably from a tutorial case), then run: openmpiKillJob 0 log.simpleFoam
Run in a single machine with multiple cores
To test if it's working, choose whether to run in WCL or MSys. Then, accordingly to the choice made: • From WCL: a. Go to the folder ofuser-2.3\pTestCase: cd ofuser-2.3\pTestCase
b. Then run: gompi Test-parallel
It will test communications between two instances of Test-parallel.exe. c. If successful, it should display something like this: C:\Program Files\blueCFD-Core-2.3\ofuser-2.3\pTestCase>mpirun -n 2 parallel
Test-parallel -
/*---------------------------------------------------------------------------*\ | ========= | \\ | | |
/
\\
/
\\
/
\\/
F ield
O peration A nd
M anipulation
|
|
| OpenFOAM: The Open Source CFD Toolbox | Version: | Web: |
|
2.3
|
www.OpenFOAM.org
| |
\*---------------------------------------------------------------------------*/ /* |
Windows 32 and 64 bit porting by blueCAPE: http://www.bluecape.com.pt
Based on Windows porting (2.0.x v4) by Symscape: http://www.symscape.com
*\ |
\*---------------------------------------------------------------------------*/ Build
: 2.3-21131bcbd876
39 | Page
©blueCAPE
blueCFD-Core 2.3 Exec
: Test-parallel.exe -parallel
Time
: 16:21:16
Date Host
: Jul 21 2010
PID
: THE_MACHINE
Case
: 712
: C:/Program Files/blueCFD-Core-2.3/ofuser-2.3/pTestCase
nProcs : 2 Slaves : 1 (
THE_MACHINE.5024 )
Pstream initialized with: floatTransfer
: 0
commsType
: nonBlocking
nProcsSimpleSum
: 0
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * // Create time [1]
Starting transfers [1]
[1] slave sending to master 0
[1] slave receiving from master 0 [0]
Starting transfers [0]
[0] master receiving from slave 1 [0] (0 1 2)
[0] master sending to slave 1 End
[1] (0 1 2)
Finalising parallel run
• From MSys terminal: a. Go to the folder ofuser-2.3/pTestCase:
cd blueCFD/ofuser-2.3/pTestCase
40 | Page
blueCFD-Core 2.3 b. Then run: foamJob -p -s Test-parallel
It will test communications between two instances of Test-parallel.exe. c. If successful, it should display something like this: ofuser@THE_MACHINE ~/OpenFOAM/ofuser-2.3/pTestCase $ foamJob -p -s Test-parallel Application : Test-parallel
Parallel processing using OPENMPI with 2 processors
Executing: mpirun -np 2 /home/ofuser/blueCFD/ofuser-2.3/linuxmingw-w64DPOpt/bin/ Test-parallel
-parallel | tee log
/*---------------------------------------------------------------------------*\ | ========= | \\ |
/
|
\\
|
F ield
/
\\
|
/
O peration
\\/
A nd
M anipulation
|
| OpenFOAM: The Open Source CFD Toolbox | Version: | Web: |
|
2.3
|
www.OpenFOAM.org
| |
\*---------------------------------------------------------------------------*/ /* |
Windows 32 and 64 bit porting by blueCAPE: http://www.bluecape.com.pt
Based on Windows porting (2.0.x v4) by Symscape: http://www.symscape.com
*\ |
\*---------------------------------------------------------------------------*/ Build
: 2.3-21131bcbd876
Date
: Jul 21 2010
Exec Time
: 16:19:31
Host PID
: Test-parallel.exe -parallel
: THE_MACHINE
Case
: 1360
: C:/Program Files/blueCFD-Core-2.3/ofuser-2.3/pTestCase
nProcs : 2 Slaves : 1 (
THE_MACHINE.3560 )
Pstream initialized with: floatTransfer
: 0
commsType
: nonBlocking
nProcsSimpleSum
: 0
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
41 | Page
©blueCAPE
blueCFD-Core 2.3 Create time [0]
Starting transfers [0]
[0] master receiving from slave 1 [1]
Starting transfers [1]
[1] slave sending to master 0[0] (0 1 2) [0] master sending to slave 1
[1] slave receiving from master 0 [1] (0 1 2) End
Finalising parallel run
Run in multiple machines in parallel
At the time of this writing, there were no experiences made at blueCAPE in using OpenMPI with multiple machines. If you are interested in this functionality: • Check the Open-MPI FAQ: http://www.open-mpi.org/faq/ • Contact blueCAPE to either give some feedback or requesting help in using this. Other than these, please check first with the MS-MPI toolbox. Before launching the application (solver or utility) in parallel with multiple machines, the premise is that all machines must be able to see the case folder, whether it's the same folder or a copy of the original folder. Therefore, you'll need to either: • Make a full copy of the case folder, after decomposing and place it in the same path on all machines. • Or share the case folder in the local network, along with mapping a drive letter to this folder. Beyond this, the default blueCFD-Core service does not support running in parallel with multiple machines. If you have this need, please contact blueCAPE for more information for this support.
42 | Page
blueCFD-Core 2.3
Troubleshooting
Open-MPI can't find any Ethernet interfaces
Symptom: Normally this happens when there isn't any network cards installed or active. Diagnosis: Check if there are really none: ipconfig /all
Check if there is any entry similar to this one: Wireless LAN adapter Wireless Network Connection: Connection-specific DNS Suffix
. :
Description . . . . . . . . . . . : Broadcom 4313 802.11b/g/n Physical Address. . . . . . . . . : 00-11-22-33-44-55 DHCP Enabled. . . . . . . . . . . : Yes Autoconfiguration Enabled . . . . : Yes
IPv4 Address. . . . . . . . . . . : 192.168.123.10(Preferred) Subnet Mask . . . . . . . . . . . : 255.255.255.0 Default Gateway . . . . . . . . . : 192.168.123.1 DHCP Server . . . . . . . . . . . : 192.168.123.1 DNS Servers . . . . . . . . . . . : 192.168.123.1 NetBIOS over Tcpip. . . . . . . . : Enabled
The important detail here is the need for a valid {{IPv4}} entry.
Solution: If no IP is found, then add Microsoft's loopback network: • On Windows XP: http://support.microsoft.com/kb/839013 • Other versions: http://technet.microsoft.com/en-us/library/ cc708322%28v=ws.10%29.aspx
43 | Page
©blueCAPE
blueCFD-Core 2.3
3.2. Configure Windows Firewall
This is where things get very complicated. For working on a secured network environment, there should always be a firewall helping out to keep the bad guys away from your precious machines. The problem is that firewalls can be tricky to be configured. This chapter will attempt to help you configure the standard Windows Firewall available with Windows 7 (and R2008 server edition). The firewall in Windows XP is not addressed, since it's rather simpler than the versions in Vista and 7. The firewall in Windows Vista and 8 are not directly addressed, but some of these instructions still apply. There are two ways to add applications to the firewall, each explained in its own section: • 3.2.1. Configure Automatically the Windows 7 Firewall - This section describes how to add applications to the firewall by using a batch file. • 3.2.2. Configure Manually the Windows Firewall - This section describes how to add applications to the firewall through the graphical interface provided by Windows.
44 | Page
blueCFD-Core 2.3
3.2.1. Configure Automatically the Windows 7 Firewall
This section describes how to automatically add OpenFOAM and MPI applications to the Windows 7 Firewall. Firstly, the preparations for the automatic adding system: 1. Create a file named addfwrule.bat with the following content: call :PROCESSFILE %~$PATH:1 GOTO EOF
:PROCESSFILE
set fwnamein=auto in %~pn1 fwnameout=auto out %~pn1
set fwnamein=%fwnamein:\=_%
fwnameout=%fwnameout:\=_%
echo "Adding or modifying: %1"
netsh advfirewall firewall set rule name="%fwnamein%" new dir=in
remoteip=localsubnet action=allow program="%1" edge=yes
IF %ERRORLEVEL% NEQ 0 netsh advfirewall firewall add rule
name="%fwnamein%" dir=in remoteip=localsubnet action=allow program="%1" edge=yes
netsh advfirewall firewall set rule name="%fwnameout%" new
dir=out remoteip=localsubnet action=allow program="%1"
IF %ERRORLEVEL% NEQ 0 netsh advfirewall firewall add rule
name="%fwnameout%" dir=out remoteip=localsubnet action=allow program="%1"
GOTO EOF :EOF
There is a copy of this file provided in the installed blueCFD-Core-2.3\docs folder if you need it. 2. Place a copy of this file addfwrule.bat in the folder blueCFDCore-2.3\OpenFOAM-2.3\bin. Now, to add applications to the firewall, you will have to 1. Start the batch file blueCFD-Core-2.3\DOS_mode.bat with administrative powers. In other words, right click on the DOC_mode.bat file and select Run as administrator. 45 | Page
©blueCAPE
blueCFD-Core 2.3 2. To add each application, you can now run in the new window the batch file addfwrule.bat along with the name of the application file to be added. For example, to add Test-parallel simply run: addfwrule Test-parallel.exe
3. Do the same for mpiexec.exe and smpd.exe (for MS-MPI) or mpirun.exe (for OpenMPI): addfwrule mpiexec.exe addfwrule smpd.exe
addfwrule mpirun.exe
Keep in mind that this will only work if the applications are available in the local PATH environment variable, which should occur with the standard blueCFD-Core installation.
46 | Page
blueCFD-Core 2.3
3.2.2. Configure Manually the Windows Firewall
This section describes how to manually add OpenFOAM and MS-MPI applications to the Windows Firewall. These instructions were designed for Windows 7 (and R2008 server), but might still apply to Windows Vista and 8. In Windows XP is just a matter of accepting that the applications are allowed to access the network. 1. Be certain of which network area is your internal network, i.e. is it Home/Private, Public or Domain. If you can't figure it out, we'll assume it's both home and public networks, at least until things are finally working. 2. Make Windows aware of all of the applications you will need to access the network. It's easier this way, since it doesn't allow for mass import of a whole application folder. This means: a. Running OpenFOAM solvers/applications in the command line with the parallel option. It doesn't matter if you run in a valid case folder or not, we just need that the application gives a hint to Windows that it's going to need network access. b. Run mpiexec (MS-MPI) or mpirun (Open-MPI) in some way that it will need to communicate with something. The simplest is to run it in the pTestCase folder with: gompi Test-parallel c. For MS-MPI, when smpd is installed from the command line with the -d option, be sure that the firewall also picked up on it and you gave it some or none permission, doesn't matter right now. d. Now, use the search function in the Control Panel and look for Windows Firewall with Advanced Security. Go to the Inbound Rules and track down the applications that were picked up by the firewall. An example is shown in the subsection "Advanced Security example".
Advanced Security example 1. This is what the advanced Windows Firewall interface looks like:
47 | Page
©blueCAPE
blueCFD-Core 2.3
2. Clicking on the button for the column Group and choosing it to sort by that column, will allow easier visibility of the added applications:
3. What we are looking for are the following applications: a. mpiexec 48 | Page
blueCFD-Core 2.3 b. smpd or Process manager service for MPICH2... c. mpirun d. the solvers/applications executed e. those who have the description: Built for blueCFD, by blueCAPE. 4. Now this is the critical part: edit each one and go to the Advanced tab (see picture below). In the group Edge traversal, change it to Allow edge traversal. This will allow applications to reply back to the remote callers! This is what is missing whenever the application, in parallel mode, stays in the same output line and doesn't go forward!
5. Last but not least, remember the first point on this list? About which network you are using? If you didn't pick the correct networks, you can either use this same tab to configure the access, or use the normal Firewall application configuration window, where you can simply check the proper column associated with the desired application, as shown below:
49 | Page
©blueCAPE
blueCFD-Core 2.3
50 | Page
blueCFD-Core 2.3
3.3. Changing MPI options
There are two files that are used to keep the default MPI to be used on MSys and CMD (Windows Command Line): • For MSys: • From Windows Explorer: blueCFD-Core-2.3\msys\home\ofuser\defaultmpi.sh • From within the MSys terminal: ~/defaultmpi.sh • The default contents on this file for a typical installation are: #export WM_MPLIB=""
export WM_MPLIB=OPENMPI #export WM_MPLIB=MPICH #export WM_MPLIB=MSMPI
• For CMD: • From Windows Explorer: blueCFD-Core-2.3\defaultmpi.bat • The default contents on this file for a typical installation are: rem set WM_MPLIB=""
set WM_MPLIB=OPENMPI
rem set WM_MPLIB=MPICH rem set WM_MPLIB=MSMPI
You can either modify these files manually or use the shortcuts, as explained in section 2.1. Start Menu. Choosing the option for not using MPI might come in handy, in case there is a particular issue that was not detect with blueCFD-Core at the time of the release.
51 | Page
©blueCAPE
blueCFD-Core 2.3
3.4. Troubleshooting
This section aims to document known problems when running applications and parallel and how to solve them.
It can't find blueCFD on the local or remote machine Problem: When running in Windows Command Line, although blueCFD is installed in the same path in all machines, mpiexec or mpirun or gompi are not able to launch on the remote machine.
Note: The following solution shouldn't be necessary as of blueCFD 2.0-1, but if it is, please inform blueCAPE (the makers of blueCFD-Core) about this! Solution: If the firewall is properly configured (or disabled), then the problem is related to the path itself. For example, if the installation path is one of the following: • C:\Program Files\blueCFD-Core-2.3 • C:\Programs\blueCFD-Core-2.3
These paths will not work very well because: 1. There is a space in the name of folder Program Files. 2. The name blueCFD-Core-2.3 has more than 8 characters. To fix each one: 1. Install blueCFD-Core in another folder, preferably in a folder where your user has full permissions. 2. Edit the file blueCFD-2.1/setvars.bat and find the line: set HOME=%~dps0
Change it to:
set HOME=%~dp0
This will disable the path collapsing method for compatibility with OpenFOAM's way of handling folders (no spaces are allowed in the original OpenFOAM, but the modified version provided with blueCFD should be able to handle such folder paths).
52 | Page
blueCFD-Core 2.3
4. Building from Source Code
This chapter aims to explain how to build source code that relies on OpenFOAM technology, due to OpenFOAM's open-source nature. It aims to address the several topics that relate to this, namely: • Using the #codeStream feature; • Building custom applications and libraries; • And building OpenFOAM from source code on Windows. In addition, as of blueCFD-Core 2.3-1, the port of OpenFOAM for Windows is built directly on Windows, therefore there are currently no instructions available on how to crosscompile blueCFD-Core's port of OpenFOAM on Linux for Windows. Therefore, this chapter is divided into the following sections: • 4.1. Using Run-time Code Compilation • 4.2. Building Custom Code • 4.3. Compiling OpenFOAM
53 | Page
©blueCAPE
blueCFD-Core 2.3
4.1. Using Run-time Code Compilation Introduction
The Run-time Code Compilation feature was introduced in OpenFOAM 2.1. With it came new coding capabilities that allow the usage of #codeStream tags for having code directly in the boundary files and dictionaries of each OpenFOAM simulation case. For more information about this feature, the reader can visit the following chapter/ sections in the OpenFOAM Users Guide and release notes: • OpenFOAM Users Guide - section Basic input/output file format, sub-section The #codeStream directive: http://www.openfoam.com/docs/user/basic-fileformat.php#codeStream • OpenFOAM® v2.1.0 release notes, page Run-time Control: http://www.openfoam.com/ version2.1.0/runtime-control.php
Tutorials
Currently with blueCFD 2.3-1, the Run-time Code Compilation feature can only be used when running from the MSys terminal. It also requires that the development packages are installed with the blueCFD-Core installer (it's the default option, see section 1.2. How to install). One particular tutorial that comes with OpenFOAM that demonstrates #codeStream and 'coded' functionObject is the located at tutorials/basic/potentialFoam/cylinder. There you can find the following details: • In the Allrun script is shown how to activate this feature, which requires copying the global controlDict file and changing the respective variable. • In the file system/controlDict is shown how to code a functionObject directly, without the need for a previously compiled external library. • In the file constant/polyMesh/blockMeshDict is shown how to create a preprogrammed mesh dictionary that will be used by blockMesh at runtime. To try it how, simply run in MSys, when already at the indicated tutorial folder, the following command: ./Allrun
For going deeper into this subject, please refer to the OpenFOAM Users Guide, as indicated in section 2.1. Start Menu.
54 | Page
blueCFD-Core 2.3
4.2. Building Custom Code Introduction
With the release of OpenFOAM 2.0 came several new features, including the Runtime Code Compilation. Starting with blueCFD 2.0-1 this feature was also released, along with the capability of building custom solvers and libraries that link directly with OpenFOAM. The reason for the original limitation regarding building OpenFOAM directly on Windows, is the one referred to since blueCFD 1.6-1 was released: OpenFOAM's source code relies on a case-sensitive file system, mirroring the same naming conventions used in the C++ code. Windows only has a case-preserving file system by default, which means that files which differ only in letter case, such as vector.H and Vector.H will be overlapped and one will be forgotten. Therefore, with the release of blueCFD 2.0-1, a semi-automatic renaming strategy has been put into action for renaming files that most likely will collide, by pre-pending the extension .T to each file name and occurrence inside other files. This criteria has been used because most files that start with an upper case first letter are C++ templates. For example, the files vector.H and Vector.H present in the original version, have the respective vector.H and Vector.T.H names in blueCFD-Core's version. At the time of this writing, the script that does the semi-automatic renaming strategy is not distributed with blueCFD-Core, because it is still in a development and proof-ofconcept testing phase.
Adapting code
To make one's own custom solvers and libraries build in Windows, the following modifications need to be made: 1. If the code to be adapted already works in Linux, then verify if there are any file collisions when unpacking in Windows. a. This can be checked simply by unpacking the code in Windows and check if the unpacking application gives any errors. b. Or by comparing the number of files and folders in Linux versus in Windows. 2. If there are file collisions within the custom code, then rename said files and folders in a Linux machine. 3. Next step is to rename the files that are included inside each source file. The simplest way to do this is to first try building the solver or library as-is (see step #5), as it should trigger error messages whenever a files is not found. 4. 55 | Page
©blueCAPE
blueCFD-Core 2.3 Taking into account that the heuristics used for renaming files depends on several details, for now the quickest way of checking these is to: a. Check all #include occurrences that include files that start with an upper case letter. With blueCFD 2.0-2, not all files starting with an upper letter have been renamed, e.g.: CourantNo.H wasn't renamed because it doesn't conflict with any other files, namely courantNo.H doesn't exist. b. For those that you already know that have renamed, check to the previously mentioned method, e.g.: Vector.H -> Vector.T.H c. Double-check in the OpenFOAM-2.3 folder on the blueCFD-Core installation for the occurrences of said file. For example, run in MSys: find $FOAM_SRC -name "Char*.H"
This will help finding out if Char.H has been renamed to Char.T.H or not. 5. Build the solver by running in MSys: wmake
Or if it is a library, then run: wmake libso
6. Two extra steps are required when building applications, where there are libraries that are not linked by default during the final stages of wmake. These are: a. Look for the missing links and add to a list the libraries to be loaded at run time: wmakeVerifyExeDependencies ./
b. Build the application once again: wmake
For going deeper into the subject of building custom code for OpenFOAM, please refer to the OpenFOAM User Guide available at the Start Menu, as detailed in section 2.1. Start Menu.
56 | Page
blueCFD-Core 2.3
4.3. Compiling OpenFOAM
As already indicated in the introductory part this chapter, as of blueCFD-Core 2.3-1, the port of OpenFOAM for Windows is built directly on Windows. This decision was taken in light of the following issues: 1. It began occurring with the library Scotch, back in OpenFOAM 1.6, where we needed to generate new header files on Windows, for then building on Linux. This was done whenever a new version of Scotch was developed. 2. Then with OpenFOAM 2.3, the CGAL library cannot be cross-compiled nor used in a cross-compilation environment, due to the complexity in the resulting machine code built into the library. Therefore, this section will address only the steps necessary for building OpenFOAM from source code on Windows. Note: When using the default blueCFD-Core installation, you do not need to build OpenFOAM from source code, since it already provides a fully working installation.
Requirements 1. Have a working blueCFD-Core installation, with MSys and the development files already present. This is a strict requirement, as the MSys installation and the GCC +mingw-w64 toolkit are needed for building OpenFOAM and some of the thirdparty libraries that OpenFOAM depends on. 2. Have the OpenFOAM source code already modified for the blueCFD-Core project, which already fixes all of the problems of building OpenFOAM on Windows. 3. It's necessary to understand how the shell environment works in MSys, as explained in section 4.3.1. Understanding the shell environment.
Steps for compiling OpenFOAM on Windows 1. Start a new MSys terminal, as explained in section 2.2. MSys Terminal. 2. Activate the desired shell environment, as explained in section 4.3.1. Understanding the shell environment. 3. Go into the ThirdParty-2.3 folder and download the necessary packages, by running the following commands: foam3rdParty
get-em source scotch=default cgal=default boost=default
metis=default tecio=default
4. Run Allwmake twice, to determine if everything builds as expected: 57 | Page
©blueCAPE
blueCFD-Core 2.3 time ./Allwmake > log.make 2>&1 time ./Allwmake > log.make 2>&1
5. The second run should give a summary of the build process, which is given in the file ThirdParty-2.3/log.make, indicating that everything is already built and installed. If not, then there has been an unforeseen error, for which you should contact blueCAPE. 6. If it all went well in step #4, then go into the main OpenFOAM-2.3 folder and run Allwmake, by running the following commands: foam
time ./Allwmake -j > log.make 2>&1
7. It will take considerable time to build everything. Somewhere 1 to 8h, depending on the CPU(s) your machine is using. While it's running, it's possible to monitor the building process, by checking the contents of the file OpenFOAM-2.3/log.make. 8. Once the script ends, it will return control to the command line. Check the contents of the file OpenFOAM-2.3/log.make. The script should have stopped when any unexpected errors occur, therefore the first problematic error should be at the end of this file. If you're unable to understand the error message, please contact blueCAPE. 9. If it all went well, then your new build of OpenFOAM is ready to be used!
58 | Page
blueCFD-Core 2.3
4.3.1. Understanding the shell environment
This section aims to briefly explain how the shell environment works. First, it's advisable to read section 2.2. MSys Terminal, before continuing reading. Please start a new MSys terminal and run this command: alias wmUNSET
As you can see, it shows this: alias wmUNSET='. $WM_PROJECT_DIR/etc/config/unset.sh'
As the output shows, the wmUNSET name is an alias for running the command that is within the single quotes. For seeing more of these aliases, simply run: alias
Now, let's deactivate the current OpenFOAM shell environment, by running: wmUNSET
If you now run the alias command, it will show considerably fewer aliases. Among those, the ones that matter are these: alias of23-32='setup_blueCFD_environment; . $FOAM_INST_DIR/OpenFOAM$OFVERSION/etc/bashrc WM_PROJECT_USER_DIR=${WM_PROJECT_USER_DIR}
FOAM_INST_DIR=${FOAM_INST_DIR} prefs-mingw-w32.sh WM_MPLIB=$WM_MPLIB' alias of23-32S='setup_blueCFD_environment; . $FOAM_INST_DIR/ OpenFOAM-$OFVERSION/etc/bashrc WM_PROJECT_USER_DIR=
${WM_PROJECT_USER_DIR} FOAM_INST_DIR=${FOAM_INST_DIR} prefs-mingww32.sh WM_PRECISION_OPTION=SP WM_MPLIB=$WM_MPLIB'
alias of23-64='setup_blueCFD_environment; . $FOAM_INST_DIR/OpenFOAM$OFVERSION/etc/bashrc WM_PROJECT_USER_DIR=${WM_PROJECT_USER_DIR}
FOAM_INST_DIR=${FOAM_INST_DIR} prefs-mingw-w64.sh WM_MPLIB=$WM_MPLIB' alias of23-64S='setup_blueCFD_environment; . $FOAM_INST_DIR/ OpenFOAM-$OFVERSION/etc/bashrc WM_PROJECT_USER_DIR=
${WM_PROJECT_USER_DIR} FOAM_INST_DIR=${FOAM_INST_DIR} prefs-mingww64.sh WM_PRECISION_OPTION=SP WM_MPLIB=$WM_MPLIB'
All of these aliases are defined in the file ~/sourceOF. There are pretty long aliases, as they include several details: 59 | Page
©blueCAPE
blueCFD-Core 2.3 1. Each alias is in a single line. 2. Each alias will run two commands, separated by a semicolon ";": a. setup_blueCFD_environment - This is a shell function, which will activate the necessary shell variables for the OpenFOAM installation provided in blueCFDCore. b. . $FOAM_INST_DIR/OpenFOAM-$OFVERSION/etc/bashrc - Notice the dot at the beginning, which acts as a command for running the contents of the file "$FOAM_INST_DIR/OpenFOAM-$OFVERSION/etc/bashrc" as if it were executed manually in this command line. c. The code after this file path defines all of the necessary scripts and shell environment variables for the OpenFOAM scripts to properly define the working environment. These are: i. WM_PROJECT_USER_DIR - This defines the path for the user folder dedicated to running OpenFOAM related code. ii. FOAM_INST_DIR - This defines the path of the base folder where the OpenFOAM related folders are located. iii. prefs-mingw-w32.sh and prefs-mingw-w64.sh - These two scripts define the base settings for the 32 and 64 architectures. Note: blueCFD-Core 2.3 officially only supports the 64-bit build. If you need the 32-bit build, please contact blueCAPE. iv. WM_PRECISION_OPTION - This defines the precision, with SP for single precision and DP for double precision (the default). v. WM_MPLIB - This defines the keyword associated to the MPI toolbox to be used. For more information, check the file "$FOAM_INST_DIR/ OpenFOAM-$OFVERSION/etc/config/settings.sh". Therefore, taking into account this information, choose if you want to run the alias respective to an already existing OpenFOAM on Windows/MSys shell environment or create your own alias. The default installation of blueCFD-Core provides the binaries respective to the alias of23-64 and it also allows building the installation associated to the alias of23-64S. Therefore, if you choose to use one of the existing/working aliases, run either one of the following: of23-64
of23-64S
But keep in mind that the one associated to of23-64S does not have a working installation by default. You'll have to follow the steps provided in the main chapter 4. Building from Source Code.
60 | Page
blueCFD-Core 2.3 For more information regarding the OpenFOAM shell environment, please refer to this wiki page: http://openfoamwiki.net/index.php/Installation/Working_with_the_Shell
61 | Page
©blueCAPE
blueCFD-Core 2.3
5. Third-Party Software
In this chapter is given some introductory notes regarding each third-party software provided in blueCFD-Core, namely any software beyond OpenFOAM. The sections are: • • • • • • • • • • •
5.1. Notepad2 5.2. ParaView 5.3. Blender 5.4. enGrid 5.5. SwiftBlock and SwiftSnap 5.6. Discretizer 5.7. Gnuplot 5.8. Python 5.9. GDB 5.10. CMake 5.11. Git
62 | Page
blueCFD-Core 2.3
5.1. Notepad2
This section aims to provide the reader with some starting points on how to use Notepad2. Official website for Notepad2: http://www.flos-freeware.ch/notepad2.html Notepad2 is very similar to Windows Notepad, with several improvements: • • • • • • • • • • • •
Syntax highlighting: HTML, XML, PHP, ASP (JS, VBS), CSS, JavaScript, VBScript, C/C++, C#, Resource Script, Makefiles, Java, Visual Basic, Pascal, Assembly, SQL, Perl, Python, Configuration Files, Apache Config Files, PowerShell, Batch Files, Diff Files Drag & drop text editing inside and outside Notepad2 Basic regular expression search and replace Useful word, line and block editing shortcuts Rectangular selection (Alt+Mouse) Brace matching, auto indent, long line marker, zoom functions Support for Unicode, UTF-8, Unix and Mac text files Open shell links Mostly adjustable
Therefore, this text editor makes it easier to edit OpenFOAM files, scripts and batch files, since it can open the Linux formatted files the OpenFOAM uses. As explained in section 1.2. How to install, when the installer is requesting user options, one of such options is to add to the pop-up menu that appears when you right-click on a file in Windows Explorer. This makes it easier to directly edit and maintain a OpenFOAM simulation cases, as long as a Windows Explorer window is kept open on the simulation case folder. Notepad2 is also accessible from both MSys and CMD terminals/command lines provided with blueCFD, simply by typing: notepad2 filename_you_want_to_open
In MSys you can open the file from the command line and continue working on the terminal with either one of the following methods: • Run notepad2 with an ampersand at the end of the line: notepad2 filename_you_want_to_open &
• Run nano with an ampersand at the end of the line: nano filename_you_want_to_open &
63 | Page
©blueCAPE
blueCFD-Core 2.3 This is because there is an alias associated to nano, which can be seen by running: alias nano
• Detach the execution of the command in MSys, by pressing the key combination Ctrl +Z and typing the command bg, which sends the process into the background.
64 | Page
blueCFD-Core 2.3
5.2. ParaView
This section is further subdivided into the following subsections: • 5.2.1. Using ParaView • 5.2.2. Using ParaView Server • 5.2.3. Miscellaneous notes
65 | Page
©blueCAPE
blueCFD-Core 2.3
5.2.1. Using ParaView
To run ParaView from the command line, it can be done with the following commands: • For opening the simulation case which was executed with OpenFOAM, run: paraFoam
• For simply opening ParaView from the command line, run: paraview
Running ParaView from the Start Menu is also possible, as indicated in section 2.1. Start Menu. For more about how to use ParaView, read: • The tutorials section on the OpenFOAM User Guide: • Online User Guide: http://www.openfoam.com/docs/user/ • Offline User Guide in PDF format, as indicated in section 2.1. Start Menu. • The documents available for ParaView, as indicated in section 2.1. Start Menu, available in the folder Documentation and Web.
66 | Page
blueCFD-Core 2.3
5.2.2. Using ParaView Server
Since version 3.10.0, ParaView now comes with its own Open-MPI installation. This allows for a quick and fast deployment of ParaView for multi-core and multi-machine scenarios. Nonetheless, the currently used plug-in for reading OpenFOAM cases can only process data with a single core. Therefore the ParaView server is currently only useful for remote connections. Another known limitation is that both the client machine and the server machine must have the same ParaView+MPI versions. In the case for ParaView that is provided with blueCFD-Core, it's only necessary to install ParaView on the client machine, but blueCFDCore has to be installed on the server machine, which is used for calculations. For more about using ParaView Server please read the following wiki pages: • http://www.paraview.org/Wiki/Setting_up_a_ParaView_Server • http://www.paraview.org/Wiki/Starting_the_server
67 | Page
©blueCAPE
blueCFD-Core 2.3
5.2.3. Miscellaneous notes
Cautions when running ParaView from MSys, directly from a shell script: • When running ParaView from MSys, an alias had to be created for launching ParaView. This will restrict the ability to run paraview with any arguments. • This hack had to be created in order to speed up ParaView's start-up. When the hack is not properly used, ParaView will take a rather long time to load and be slow in some operations. This is due to the tremendous length the environment PATH variable has under MSys with the activated OpenFOAM environment. • When running paraFoam from MSys, a very similar hack is used, but the arguments for running with paraFoam still work. The alias parafoam was also created, for the users that are familiar with the permissive nature of Windows. • To see what these alias defined commands do exactly, run in MSys: alias paraview alias paraFoam
68 | Page
blueCFD-Core 2.3
5.3. Blender
This section currently only gives a brief description on where the reader can search for more information on using Blender. Blender was added starting with blueCFD-Core 2.0-2 to provide users with a good application for CAD geometry design, manipulation and fixing. The major reason is in fact due to the available information provided at enGrid's wiki on how to use both Blender and enGrid. For more, see the section 5.4. enGrid. To run Blender from the command line, simply run: blender
To run Blender from the Start Menu, see section 2.1. Start Menu.
69 | Page
©blueCAPE
blueCFD-Core 2.3
5.4. enGrid
This section currently only gives a brief description on where the reader can search for more information on using enGrid. enGrid was introduced starting with blueCFD-Core 2.0-2 with the hope to bring a more serious and friendlier mesh generator and a very basic GUI for OpenFOAM. Currently there isn't much written about this latter feature, nor is it working properly with the latest versions of OpenFOAM, but hopefully more information and features with appear as enGrid's user base continues to grow.
Getting started
Brief overview on how to use enGrid: 1. To run enGrid on blueCFD-Core, there are three ways of doing it: a. From MSys: engridFoam
b. From WCL (Windows Command Line): engrid
c. From the Start Menu, as described in section 2.1. Start Menu. 2. A complete guide on how to use enGrid is currently only available for enGrid 1.3, provided on enGrid's wiki: https://github.com/enGits/engrid/wiki/Complete-Meshfor-a-damper-in-a-duct-%28starting-from-an-STL-geometry%29 Notes: a. Notice that all surfaces have their own boundary code. This is due to enGrid's way of generating or improving the surface mesh. b. Always verify if your mesh is sane. c. The surface mesh will not be modified or improved if the respective surface refinement rules are not added. 3. Learn how to create a geometry in Blender and subsequently export it to enGrid:https://github.com/enGits/engrid/wiki/Unstructured-Grids-for-OpenFOAMWith-Blender-and-enGrid-1.2 Details to keep in mind: a. On blueCFD-Core, Blender is accessible on the Start Menu, as described in section 2.1. Start Menu. b. Verify if your geometry is sane and fix it if necessary: https://github.com/ enGits/engrid/wiki/Unstructured-Grids-for-OpenFOAM-With-Blender-andenGrid-1.2#wiki-Advanced_Editing_and_Repairing_Geometries c. Export to enGrid: https://github.com/enGits/engrid/wiki/Unstructured-Gridsfor-OpenFOAM-With-Blender-and-enGrid-1.2#wiki-Exporting_the_Model d. The second part of this second tutorial shown provides outdated information, but it can still prove to be very useful information: https://github.com/ 70 | Page
blueCFD-Core 2.3 enGits/engrid/wiki/Unstructured-Grids-for-OpenFOAM-With-Blender-andenGrid-1.2#wiki-Meshing_with_enGrid e. Do as you learned on the first tutorial and remember the notes associated with it. For more information, visit the following forums: • The official enGrid forum: http://www.cfd-online.com/Forums/engrid/ • The sub-forum at CFD-Online related to OpenFOAM and open-source meshers: http://www.cfd-online.com/Forums/openfoam-meshing-open/
Installing scripts in Blender
As of blueCFD-Core 2.3-1, the enGrid add-ons (import and export) are pre-installed in the provided Blender version, but they are not activated by default. To activate and install these add-ons, follow the steps provided in the official Blender wiki: http:// wiki.blender.org/index.php/Doc:2.6/Manual/Extensions/Python/Add-Ons
71 | Page
©blueCAPE
blueCFD-Core 2.3
5.5. SwiftBlock and SwiftSnap
SwiftBlock and SwiftSnap are two add-ons for Blender, designed for assisting the user in setting up from simple to advanced blockMeshDict and snappyHexMeshDict files respectively, both from within Blender. These add-ons are pre-installed in Blender as of blueCFD-Core 2.3-1, but they are not activated by default. To activate and install these add-ons, follow the steps provided in the official Blender wiki: http://wiki.blender.org/index.php/Doc:2.6/Manual/Extensions/ Python/Add-Ons The respective guides for these add-ons are provided here: • SwiftBlock: http://openfoamwiki.net/index.php/Contrib/SwiftBlock • SwiftSnap: http://openfoamwiki.net/index.php/Contrib/SwiftSnap
72 | Page
blueCFD-Core 2.3
5.6. Discretizer
This article is a rough guide to the Discretizer version distributed with blueCFD. Here it's explained on how to start using the two available GUIs: • Discretizer - the geometry designer and mesher. • Discretizer::Setup - helps setup and run simulations. This section is divided into the following subsections: • 5.6.1. Using Discretizer • 5.6.2. Using Discretizer::Setup • 5.6.3. Updating Discretizer Note: The source code for Discretizer should be working in blueCFD 2.3-1 version, as it was based on the version provided in Discretizer's SVN. Björn Bergqvist is the author of Discretizer and should be contacted whenever there are problems with his applications, as well as to give support. Links: • Email contact: [email protected] • Twitter: @discretizer • Thread at cfd-online.com: http://www.cfd-online.com/Forums/openfoam-meshingother/63919-discretizer-free-mesh-program-cfd-computational-fluid-dynamics.html • Donations: http://sourceforge.net/project/project_donations.php?group_id=160770 • Website of Discretizer: http://www.discretizer.org/ • Discretizer @ sourceforge.net: http://sourceforge.net/projects/discretizer/ • About Discretizer: http://www.discretizer.org/node/6
73 | Page
©blueCAPE
blueCFD-Core 2.3
5.6.1. Using Discretizer Introduction
Currently Discretizer is only available in 32bit for Windows, because it relies on Ruby to work. At the time of this writing, March 2014, the 64-bit version of Ruby for Windows is still gaining strength. Discretizer's main function is help the user to define the geometries for the desired case to be executed, and then it will to create meshes for running with OpenFOAM. It can provide you with basic case set-up, but it is limited for now. Keep in mind that Discretizer is still in development by its creator Björn Bergqvist. It is yet to reach a version that can be called Discretizer 1.0. So, there are at least three possibilities for Discretizer to malfunction: • that particular bug hasn't been found yet or fixed. • it is a feature that is yet to be implemented. • it failed only because it hasn't been tested properly to run in Windows! So, in any cases, you should: • Write down the steps taken to make Discretizer to break. • Then try to recreate the steps again, to check if it breaks again. • If the problem is related to 1 or 2, you should contact the creator of Discretizer. If the problem is 3, then you should contact blueCAPE. When in doubt, contact blueCAPE!
Running Discretizer
As mentioned in the chapter 2. Getting Started, there are two ways to use OpenFOAM under Windows with blueCFD: • Using MSys, a terminal similar interface to Linux/Unix, giving a near Linux experience; • Using Windows Command Line (WCL), a terminal interface similar to DOS. In either one, you can launch Discretizer by running: discretizer
You can also launch it from the Start Menu shortcut, as shown in section 2.1. Start Menu. Follow the instructions in Discretizer's Manual, available in the Start Menu, folder Documentation, as described in section 2.1. Start Menu.
74 | Page
blueCFD-Core 2.3 At all times, keep a Windows Explorer window open in the folder where you are going to work with Discretizer. This will prove more than useful, because Discretizer doesn't have the full capabilities that you may have grown familiar in Windows. So, the copypaste trick of the folder path from the Explorer address bar, into Discretizer's file open dialogues and fields, can come quite in handy! There are some details to keep in mind, when using Discretizer in Windows: • The path ~/ in the OpenFOAM Run Dialog has two meanings: a. in MSys means that it is the home folder, namely /home/ofuser/. b. in WCL could have different meanings, but the most common one is that it is the folder where blueCFD-Core is installed. This is also the case when you start Discretizer from the Start Menu. • So, taking into account the previous point, when running from WCL, you should always use the absolute path to your work folder. • When running from MSys, you can use both nomenclatures: Linux and Windows, i.e., referred as /home/... or C:\Programs... respectively. • As documented in the Discretizer Manual, the terminal from which you launch Discretizer shows what Discretizer is doing in the background! This is useful for when running things with Discretizer. • Again, as it is written in the Introduction to Discretizer section: Discretizer is still a work in progress! Please give (moral) support and feedback to its creator Björn Bergqvist (contacts available in the main section 5.6. Discretizer)!
Working with Discretizer
Currently there is no tutorial is provided with blueCFD-Core. Nonetheless, the official site has a few screencasts on how to use Discretizer: http://www.discretizer.org/ node/14 Note: At the time of the release of blueCFD-Core 2.3-1, Discretizer can end with a bitter taste when it exits, mainly due to a bug with the pre-package Ruby version that is distributed with Discretizer.
75 | Page
©blueCAPE
blueCFD-Core 2.3
5.6.2. Using Discretizer::Setup Introduction
Discretizer::Setup is also still in development. Its main objective is to provide a GUI for setting up and running cases in OpenFOAM. It seems to be far from being complete, and its usage is still very limited. You can see this as a technology preview application. We at blueCAPE-Core have not been able to use this in real case scenarios, so we can only tell you that the things to keep in mind for Discretizer also applies to Discretizer::Setup.
Running Discretizer::Setup
As mentioned in the chapter 2. Getting Started, there are two ways to use OpenFOAM under Windows with blueCFD: • Using MSys, a terminal similar interface to Linux/Unix, giving a near Linux experience; • Using Windows Command Line (WCL), a terminal interface similar to DOS. In either one, you can launch Discretizer by running: discretizerSetup
You can also launch it from the Start Menu shortcut, as shown in section 2.1. Start Menu.
Working with Discretizer::Setup
Currently there is no tutorial is provided with blueCFD-Core. Nonetheless, the official site has a few screencasts on how to use Discretizer: http://www.discretizer.org/node/14 Note: At the time of the release of blueCFD-Core 2.3-1, Discretizer can end with a bitter taste when it exits, mainly due to a bug with the pre-package Ruby version that is distributed with Discretizer.
76 | Page
blueCFD-Core 2.3
5.6.3. Updating Discretizer
We at blueCAPE will try to release updates for Discretizer when deemed necessary or when blueCFD-Core users demand its update. You can update Discretizer yourself, but be advised to first backup the blueCFDCore-2.3\ThirdParty-2.3\discretizer folder before updating it. Update experiences may vary... If you wish to update: 1. Download the official package created for Windows from http://www.discretizer.org 2. Go to where Discretizer is installed, namely blueCFDCore-2.3\ThirdParty-2.3\discretizer and erase the contents of that folder expect for the folder bin. 3. Unpack the newly downloaded package. 4. Copy/move the contents of the extracted package (its what is inside the parent folder discretizer) into blueCFD-Core-2.3\ThirdParty-2.3\discretizer.
77 | Page
©blueCAPE
blueCFD-Core 2.3
5.7. Gnuplot
This article currently only provides the reader with some starting points on how to use Gnuplot. The links and shortcuts for Gnuplot are provided in the Star Menu, as documented in section 2.1. Start Menu. There you'll find: • The link for the home of Gnuplot: http://www.gnuplot.info • Several documents are provided at the Documentation subfolder. • Two shortcuts for launching the Gnuplot shell in text mode and GUI mode. As for using Gnuplot with OpenFOAM, there are a few examples already provided with OpenFOAM: • The plateHole tutorial, as shown in the OpenFOAM User Guide: http:// www.openfoam.com/docs/user/plateHole.php • Two other tutorials show how this is used in their Allrun script:
a. incompressible/boundaryFoam/boundaryWallFunctionsProfile/ b. tutorials/mesh/moveDynamicMesh/simpleHarmonicMotion/
78 | Page
blueCFD-Core 2.3
5.8. Python
This article currently only provides the reader with some starting points on how to use Python with blueCFD-Core. Website for Python: http://www.python.org
Introduction
Currently, Python can be installed in blueCFD-Core because PyFoam can be installed by the user. Nonetheless, Python is a very powerful interpreted programming language (i.e. can work as you code) which can be put into very good use when working with OpenFOAM. In addition, the same version of Python is installed to match the version that ParaView uses, therefore allowing the user to use ParaView and VTK from Python, as long as python is launched from one of blueCFD-Core command line interfaces.
Using Python
Running Python scripts in Windows will depend on the terminal/command line interface one is using: • In WCL, simply run: python path/to/script [options for script]
• In MSys, things get a bit more complicated, simply because Python does not work well with how MSys handles the output stream. To use Python in MSys, the following launch sequence must be used: start //B //WAIT python path\\to\\script [options for script]
Notice the need of double slashes '/' and double backslashes '\'.
Also, when using Python in an MSys terminal, a file named .pythonrc already placed in the user's home folder /home/ofuser, has a few additional tweaks for making it a bit easier to use the Python shell. The contents of said file at the time of this writing is as follows: from sys import exit as quit
79 | Page
©blueCAPE
blueCFD-Core 2.3
5.9. GDB
This article currently only gives a brief description on where the reader can search for more information on using GDB - the GNU Debugger. Most of links written on this article are also provided in the Start Menu, as seen in section 2.1. Start Menu. To get the reader started with using GDB, there are (at the very least) two very good tutorials online for taking the first steps in using GDB: • Online Tutorial by Peter Jay Salzman: http://dirac.org/linux/gdb/ • Online Tutorial by Norman Matloff: http://heather.cs.ucdavis.edu/~matloff/UnixAndC/ CLanguage/Debug.html These two have joined forces and written a book entitled "The Art of Debugging with GDB, DDD, and Eclipse", which might come in handy if the reader wishes to use GDB with all of its might. As for GDB itself, the home of GDB is at http://www.gnu.org/s/gdb/ - with a lengthy list of documents at http://www.gnu.org/s/gdb/documentation/ The official online manual is provided at http://sourceware.org/gdb/current/onlinedocs/ gdb/ Last but not least, there is a community contribution project at http://openfoamwiki.net named gdbOF: http://openfoamwiki.net/index.php/Contrib_gdbOF gdbOF is an attachable to GNU debugger (gdb) tool that includes macros to debug OpenFOAM's solvers and applications in an easier way.
This has not been tested yet with blueCFD-Core, but if the reader is interested in this, feel free to try it and/or give the people at blueCAPE (the makers of blueCFD-Core) some feedback on this topic.
80 | Page
blueCFD-Core 2.3
5.10. CMake
CMake was added starting with blueCFD-Core 2.0-2 in foresight of future code to be provided with blueCFD-Core and mainly to be compiled on the user's side. In blueCFDCore 2.1-2, it could be used CMake for building ofgpu directly on Windows, which will be re-released in blueCFD-Core 2.3-2. In the meantime, it comes in handy for building CGAL from source code. The links that are installed by default with CMake are provided at the Start Menu (see section 2.1. Start Menu). These are: • CMake website: http://www.cmake.org • CMake Online Documentation: http://www.cmake.org/cmake/help/ documentation.html • CMake Wiki: http://www.cmake.org/Wiki/CMake A few interesting wiki pages: a. FAQ (Frequently asked questions): http://www.cmake.org/Wiki/CMake_FAQ b. A Simple CMake Example: http://www.cmake.org/HTML/Examples.html c. Tutorial on using CPack: http://www.cmake.org/Wiki/ CMake:Packaging_With_CPack
81 | Page
©blueCAPE
blueCFD-Core 2.3
5.11. Git
As of blueCFD-Core 2.3-1, Git is provided as part of the MSys installation. This means that it's possible to fully take advantage of the development lines available for OpenFOAM source code and related community source code. The following tutorials for using Git as suggested, for getting started: • http://git-scm.com/book/en/Getting-Started • http://git-scm.com/documentation • http://git-scm.com/book
82 | Page