Recent changes to UserGuide

UserGuide modified by Bruno Santos

Bruno Santos — Wed, 25 Mar 2015 23:10:50 -0000

--- v1
+++ v2
@@ -1,17 +1,17 @@
 Table of Contents:

-  * Quick Start
-  * Installation
-    * ParaView
-  * Usage Notes
-    * Using Windows Command Line (CMD)
-    * Adapting simulation cases from Linux to Windows
-    * Working with OpenFOAM text files
-      * Installing Notepad2 manually
-    * Using advanced features
-      * Changing running options
-        * Disabling stack tracing
-        * Adding/Modifying Environment Variables
+  * [Quick Start](#quick-start)
+  * [Installation](#installation)
+    * [ParaView](#paraview)
+  * [Usage Notes](#usage-notes)
+    * [Using Windows Command Line (CMD)](#using-windows-command-line-cmd)
+    * [Adapting simulation cases from Linux to Windows](#adapting-simulation-cases-from-linux-to-windows)
+    * [Working with OpenFOAM text files](#working-with-openfoam-text-files)
+      * [Installing Notepad2 manually](#installing-notepad2-manually)
+    * [Using advanced features](#using-advanced-features)
+      * [Changing running options](#changing-running-options)
+        * [Disabling stack tracing](#disabling-stack-tracing)
+        * [Adding/Modifying Environment Variables](#addingmodifying-environment-variables)

@@ -80,14 +80,14 @@

     set PATH=%PATH%;C:\Program Files\ParaView 3.12.0\bin

-* Save and close the file `ParaView.bat`. 
+  6. Save and close the file `ParaView.bat`. 

 # Usage Notes

-In this chapter the reader is introduced to the basics of using blueCFD-SingleCore and a few tips on how to get around it. It examplifies the usage for blueCFD-SingleCore 2.0, but it should work with all versions. 
+In this chapter the reader is introduced to the basics of using blueCFD-SingleCore and a few tips on how to get around it. It exemplifies the usage for blueCFD-SingleCore 2.0, but it should work with all versions. 

 ## Using Windows Command Line (CMD)

@@ -117,16 +117,14 @@

   * Under CMD, only a few scripts 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` \- does **not** work in **blueCFD-SingleCore**, but if you cross-compile the code yourself, you can type: 
-    
-    gompi <solver_application> <solver_options>
+    * `gompi.bat` \- does **not** work in **blueCFD-SingleCore**, but if you cross-compile the code yourself, you can type: 

+    `gompi <solver_application> <solver_options>`
+    
And it will launch the application using the selected MPI during start-up. 

-> And it will launch the application using the selected MPI during start-up. 
-
-* `codehelp.bat` \- it will launch the offline code help 
-* With CMD, the only editor usable from inside the command line window is `edit`. You can also use Notepad2, if you installed it yourself (see section Working with OpenFOAM text files). 
-* CMD terminal 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 manual, and/or programmers manual (both available at `Start->Programs->blueCFD-SingleCore-2.0->OpenFOAM`) and/or see check the links at `Start->Programs->blueCFD-SingleCore-2.0->Links`. 
+  * `codehelp.bat` \- it will launch the offline code help 
+  * With CMD, the only editor usable from inside the command line window is `edit`. You can also use Notepad2, if you installed it yourself (see section Working with OpenFOAM text files). 
+  * CMD terminal 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 manual, and/or programmers manual (both available at `Start->Programs->blueCFD-SingleCore-2.0->OpenFOAM`) and/or see check the links at `Start->Programs->blueCFD-SingleCore-2.0->Links`. 

 ## Adapting simulation cases from Linux to Windows

@@ -197,4 +195,4 @@
   * `OpenFOAM-2.0/etc/config/settings.sh` \- Has additional settings for the OpenFOAM environment variables for usage in Linux, Cygwin and MSys. 
   * `OpenFOAM-2.0\etc\batchrc.bat` \- Has a subset of the environment variables from the previous two files, for usage in the Windows Command Line (CMD). 

-There is also an accessory folder for dynamically updating and loading additional variables for usage with blueCFD-SingleCore's installation structure. This folder is `OpenFOAM-2.0/etc/config.d/`, where files with the extension `.bat` are loaded in CMD. There you'll find several files, depending on the installation options. It's left to the reader to investigate how these can be modified and/or created for extending one's needs. 
+There is also an accessory folder for dynamically updating and loading additional variables for usage with blueCFD-SingleCore's installation structure. This folder is `OpenFOAM-2.0/etc/config.d/`, where files with the extension `.bat` are loaded in CMD. There you'll find several files, depending on the installation options. It's left to the reader to investigate how these can be modified and/or created for extending one's needs.

UserGuide modified by Anonymous

Anonymous — Wed, 25 Mar 2015 20:58:02 -0000

Table of Contents:

Quick Start
Installation
- ParaView
Usage Notes
- Using Windows Command Line (CMD)
- Adapting simulation cases from Linux to Windows
- Working with OpenFOAM text files
- Installing Notepad2 manually
- Using advanced features
- Changing running options
  - Disabling stack tracing
  - Adding/Modifying Environment Variables

Quick Start

In case you already are already familiar with the Windows Command Line (CMD), here is a few brief instructions.

To the left you should be able to find the blueCFD-SingleCore installers. Summary of instructions on how to install blueCFD-SingleCore:

Download and install blueCFD-SingleCore. It will in turn download and install the selected options.
After installed, a new group named "blueCFD-SingleCore 2.x" (x=0,1) should be created in your Windows start menu.
- There you will find links for launching a Windows Command Line for a particular architecture.
- There you will also find several other useful links.
Follow the instructions for OpenFOAM's official online User Guide. You should take into account that some commands will have to be adapted to the Windows Command Line (CMD). For example:
- In Linux: cp -r $FOAM_TUTORIALS $FOAM_RUN
- In Windows: xcopy /S /E %FOAM_TUTORIALS%\*.* %FOAM_RUN%\

For more, continue reading.

Installation

When running the installer blueCFD-SingleCore-2.x-y-setup.exe (x>=0, y>=1), if a dialogue box pops up, it will read the following text:

You seem to be either an Administrator or a Power User of this machine, so you have two possible installation methods:

Press the "Yes" button for installing blueCFD-SingleCore for all users.
Or Press the "No" button for installing for yourself only.

Be advised that when installing blueCFD-SingleCore for all users, you should install it in a permissive folder, such as "C:\blueCFD-SC-2.0".

Here is what each option entails:

If you answer Yes:
1. The setup application will try to install it in the Program Files folder in the machine where the installer is being executed.
  As a global installation, the following default folders will be used:
2. Windows 32bit: C:\Program Files
3. Windows 64bit: C:\Program Files (x86)
4. The global Start Menu folder (on the Windows symbol button on the lower left corner) will be used for placing the links and shortcuts for the installed features of blueCFD-SingleCore.
5. Nonetheless, the blueCFD-SingleCore installer currently does not take into account more complex installation folder structures. In other words, blueCFD-SingleCore is currently hard-coded for a single user named ofuser, in order to avoid problems with spaces in user names.
6. After choosing the installation mode (or custom options), you'll be presented with the list of options chosen to be installed.
7. When using the downloadable version of blueCFD-SingleCore, most of those options will need to download the necessary packages to be installed along with it. In case the download fails, you'll be instructed that a list of files to be downloaded is provided on the respective downloads folder. Please download them manually in case the installer cannot download them on its own.
If you answer No:
1. The setup application will try to install it in your personal working area.
  By installing in your personal work area, the default folders to be used are as follows:
2. The default target folder path will be based on your personal Application Data folder. This will vary depending on your Windows version and said folder is sometimes hidden. The usual folder where blueCFD will ask to be installed at is:
  - Windows XP: C:\Documents and Settings\your user name here\Application Data\blueCFD-2.0
  - Windows Vista and 7: C:\Users\your user name here\AppData\Roaming\blueCFD-2.0
3. Your personal Start Menu folder (on the Windows symbol button on the lower left corner) will be used for placing the links and shortcuts for the installed features of blueCFD-SingleCore.
4. During installation you will be asked if those are in fact the folders where you want to place blueCFD-SingleCore, which you can change.
  Keep in mind that if you install blueCFD-SingleCore in some other location, the links and shortcuts will only be accessible to your user on:
5. the machine where you installed blueCFD-SingleCore;
6. or in your transferable account, in case of a domain installation at your work office. Warning: This means that somewhere between 0.8 and 1.4GB of data will be copied to your roaming account on the domain server! Contact your systems administrator for more information.
7. After choosing the installation mode (or custom options), you'll be presented with the list of options chosen to be installed.
8. When using the downloadable version of blueCFD-SingleCore, most of those options will need to download the necessary packages to be installed along with it. In case the download fails, you'll be instructed that a list of files to be downloaded is provided on the respective downloads folder. Please download them manually in case the installer cannot download them on its own.

ParaView

ParaView has to be installed manually:

Download ParaView from here: http://www.paraview.org/
Install it wherever you want to.
Go to the blueCFD-SingleCore start menu and pick Browse blueCFD-SingleCore folder.
Go into the folder OpenFOAM-*\etc\config.d and create a file named: ParaView.bat
Edit that file with Notepad or Notepad2 and place there a line of code similar to the following one:

set PATH=%PATH%;C:\Program Files\ParaView 3.12.0\bin
Save and close the file ParaView.bat.

Usage Notes

In this chapter the reader is introduced to the basics of using blueCFD-SingleCore and a few tips on how to get around it. It examplifies the usage for blueCFD-SingleCore 2.0, but it should work with all versions.

Using Windows Command Line (CMD)

To start a Windows Command Line window with a desired architecture, go to the group at the Start Menu entitled blueCFD-SingleCore 2.0 and select one of the following shortcuts (depends on installation options):

Command Line with mingw-w32 DP
Command Line with mingw-w32 SP
Command Line with mingw-w64 DP

When this is done, you will be given the prompt. Should be something like C:\Program Files\blueCFD-SingleCore-2.0>.

Next we will follow the initial steps of the official OpenFOAM User Guide. The usual work folder should be at blueCFD-SingleCore-2.0\ofuser-2.0\. Run the following commands:

cd ofuser-2.0
mkdir run

This will create the run folder, for running your OpenFOAM cases. In Windows, this folder will be at blueCFD-SingleCore-2.0\ofuser-2.0\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 User Guide (see link inside Start->Programs->blueCFD-SingleCore-2.0->OpenFOAM), starting page U-20, or online at Lid-driven cavity flow. You should be able to run most of the commands available there.

Things to keep in mind:

Under CMD, only a few scripts 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 - does not work in blueCFD-SingleCore, but if you cross-compile the code yourself, you can type:
gompi <solver_application> <solver_options>

And it will launch the application using the selected MPI during start-up.

codehelp.bat - it will launch the offline code help
With CMD, the only editor usable from inside the command line window is edit. You can also use Notepad2, if you installed it yourself (see section Working with OpenFOAM text files).
CMD terminal 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 manual, and/or programmers manual (both available at Start->Programs->blueCFD-SingleCore-2.0->OpenFOAM) and/or see check the links at Start->Programs->blueCFD-SingleCore-2.0->Links.

Adapting simulation cases from Linux to Windows

There are several situations where the simulation cases that work in Linux, will not work in Windows without some additional modifications. In a nutshell, the documented situations are:

In cht*MultiRegionFoam tutorials, the field variable K has been renamed to K_, but only file wise! It is still referenced as K as a code object. This means that the changeDictionaryDict files need to change K to K_. It might also affect the fvSolution files as well, but only in references to the file name itself. The script chtMultiRegionFixK should help fix these issues, although this has to be done in Linux/Cygwin/MSys:

chtMultiRegionFixK folder/path/to/tutorial
In PDRFoam* tutorials, the field B has been renamed B_, similarly to the previous point. The script PDRFoamFixB should help fix these issues:

PDRFoamFixB folder/path/to/tutorial
STL files that have special characters should be have their solid names modified to compatible names. Such example is the tutorial incompressible/simpleFoam/motorBike, where the script fixForWindows fixes these issues:

./fixForWindows
In the Windows build, the solvers will create time folders with 3 digits in the base 10 exponent. For example, in Linux, a time folder named 1e-08 will be named 1e-008 in Windows.
For more, see the script prepareTutorials4Win:

which prepareTutorials4Win

Working with OpenFOAM text files

Windows Notepad is not capable of handling text files saved in Linux. This is because the characters for ending lines in Windows and in Linux are not exactly the same.

Therefore, we at blueCAPE suggest users to use Notepad2 since it's one of the closest text editors to Windows Notepad as well as carrying very nice features with it.

Installing Notepad2 manually

If you wish to install it manually (or have already installed it), you can also associate Notepad2 to every file, making it available from the right-click menu on Windows Explorer. For that, create a file named something like autoregNotepad.reg and put inside it the following code:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\*\shell]

[HKEY_CLASSES_ROOT\*\shell\Notepad2]
@="Open with &Notepad2"

[HKEY_CLASSES_ROOT\*\shell\Notepad2\command]
@="\"C:\\ProgramsFree\\notepad2\\Notepad2.exe\" \"%1\""

You should change the path for Notepad2 accordingly to where you installed it.

Other suggestions for text editors, in increasing degree of complexity+features are:

Notepad++: http://notepad-plus-plus.org/
Geany: http://www.geany.org/Download/Releases
Eclipse IDE (Classic): http://www.eclipse.org/downloads/

Using advanced features

Changing running options

Disabling stack tracing

Stack tracing was a new introduction in blueCFD 2.0-1. It has been officially supported in OpenFOAM on POSIX system for years now, but only now has it been put into work in Windows by blueCAPE. Nonetheless, this feature has not yet been tested to the maximum extend, so there might still exist some quirks to sort out.

So, in case the solver or utility crashes during the call to print stack, try disabling said tracer before running the solver/utility, by running:

set FOAM_STACKTRACE_DISABLE=1

Adding/Modifying Environment Variables

There are 3 main files that have relevant environment variables, all defined for the core OpenFOAM functionality:

OpenFOAM-2.0/etc/bashrc - Has the base OpenFOAM environment variables for usage in Linux, Cygwin and MSys.
OpenFOAM-2.0/etc/config/settings.sh - Has additional settings for the OpenFOAM environment variables for usage in Linux, Cygwin and MSys.
OpenFOAM-2.0\etc\batchrc.bat - Has a subset of the environment variables from the previous two files, for usage in the Windows Command Line (CMD).

There is also an accessory folder for dynamically updating and loading additional variables for usage with blueCFD-SingleCore's installation structure. This folder is OpenFOAM-2.0/etc/config.d/, where files with the extension .bat are loaded in CMD. There you'll find several files, depending on the installation options. It's left to the reader to investigate how these can be modified and/or created for extending one's needs.