OpenFOAM Debugging

Debugging is often an essential part of software development. In the scope of this tutorial, I will present a couple of tools with OpenFOAM as a practical example of a C+±based scientific simulation code. After a brief reminder aboute the installation procedure of the OpenFOAM flavor foam-extend 4.1, the blog article introduces debugging with gdb and the IDEs Visual Studio Code and Qtcreator.

The demo problem is based on the pitzDaily tutorial in foam-extend and uses the scalarTransportFoam solver which implements the equation:
𝛿𝑇𝛿𝑡+∇⋅(𝑢𝑇)−∇⋅(∇𝐷𝑇𝑇)=𝑆

The geometry of the case is shown in Paraview below:

Requirements – OpenFOAM base installation Ubuntu 20.04 LTS

The tutorial assumes that you are running a system with Ubuntu 20.04 LTS installed. It is based on the installation instructions from the OpenFOAMwiki. The required base packages can be then installed using the following commands:

sudo apt-get update 
sudo apt-get install git-core build-essential binutils-dev cmake 
                     flex zlib1g-dev libncurses5-dev curl bison \
                     libxt-dev rpm mercurial graphviz python \ 
                     python-dev gcc-7 g++-7 paraview gdb

The source code of foam-extend 4.1 is available as a git repository at Sourceforge.net and can be cloned using the following commands:

mkdir ~/foam
cd ~/foam
git clone http://git.code.sf.net/p/foam-extend/foam-extend-4.1 foam-extend-4.1

For a successful building of foam-extend-4.1, we will use here GCC-7. In order to configure foam-extend to use it we need to add the following lines to etc/prefs.sh in the OpenFOAM folder:

export WM_CC='gcc-7'
export WM_CXX='g++-7'

We apply the changes by sourcing the OpenFOAM bashrc file by executing the following line in the terminal:

source etc/bashrc

sed -i -e 's=rpmbuild --define=rpmbuild --define \
            "_build_id_links none" --define=' \
            ThirdParty/tools/makeThirdPartyFunctionsForRPM
sed -i -e 's/gcc/\$(WM_CC)/' wmake/rules/linux64Gcc/c
sed -i -e 's/g++/\$(WM_CXX)/' wmake/rules/linux64Gcc/c++

In order to use both the productive and debug versions easily, it is convienient to define correseponding aliases. In order to do so the two lines should be added to the .bashrc file in the home directory. This can be either done by copying and pasting the following two lines to the terminal window or by manually adding the text between the quotation marks with your favorite text editor.

echo "alias fe41='source \ 
            \$HOME/foam/foam-extend-4.1/etc/bashrc'" >> ~/.bashrc
echo "alias fe41_debug='source \
            \$HOME/foam/foam-extend-4.1/etc/bashrc \
            WM_COMPILE_OPTION=Debug'" >> ~/.bashrc

With this setup it is possible to compile both the optimized and the debug version using the following commands:

cd ~/foam/foam-extend-4.1
source ~/foam/foam-extend-4.1/etc/bashrc
./Allwmake.firstInstall
WM_COMPILE_OPTION=Debug ./Allwmake

The discussed IDEs QtCreator and Visual Studio Code are installed using
the package management system using:

sudo apt-get install qtcreator
snap install code --classic

The code needed for this tutorial can be found here.

Debugging Tools

Basic debugging can be accomplished by sending text messages to the terminal through the addition of “Info” sections. This approach helps in understanding the execution flow of the code and pinpointing where it stops working.

Info<< "\nStarting time loop\n" << endl;

while (runTime.loop())
{
    Info<< "Time = " << runTime.timeName() << nl << endl;
      ...
}

However, there are some downsides to this method. It offers no control over the code during execution, requires modifying and recompiling the code, and necessitates cleaning up the code after successful debugging.

Understanding Debug Switches in OpenFOAM

In OpenFOAM, debug switches offer a flexible way to manage debugging information without the need for recompilation, unlike traditional “Info” statements. These switches can be turned on and off and are defined in the controlDict for a specific case, allowing users to set different debug levels to control the verbosity of the output.

Key Features of Debug Switches

  • Debug Levels:
    • 0: No debug information.
    • Levels 1, 2, 3, etc.: Increasing levels of verbosity.
  • No Recompilation Required:
    • Unlike “Info” statements, which require modifying and recompiling the code, debug switches are built-in and can be activated or deactivated without recompilation.
  • Class-Specific Statements:
    • Debug statements are defined for most classes within OpenFOAM, providing targeted and relevant debugging information.

Using Debug Switches

To view and manage active debug switches, OpenFOAM offers specific commands:

  • Listing Registered Switches:
    • For OpenFOAM Foundation and ESI versions: pisoFoam -listRegisteredSwitches
    • For foam-extend versions: pisoFoam -dumpControlSwitches
  • Activating Debug Switches:
    • For OpenFOAM Foundation and ESI versions: pisoFoam -debug-switch <name=val>
    • For foam-extend versions: pisoFoam -DebugSwitches <key1=val1,key2=val2,...>

These commands allow users to dynamically list and activate debug switches, providing an efficient way to control and monitor the execution flow and behavior of solvers within OpenFOAM.

Using GDB for Debugging in OpenFOAM

The GNU Debugger (gdb) is a powerful tool for studying the run-time behavior of your code, examining variables, and making changes to the program while it is running. This capability makes gdb an invaluable tool for in-depth debugging and analysis. However, there are some trade-offs to consider.

Key Features of gdb

  1. Run-Time Behavior Analysis:
    gdb allows you to closely study how your code behaves during execution, providing insights that are difficult to obtain through static analysis.
  2. Examining Variables:
    You can inspect the values of variables at various points during execution, helping to identify bugs and understand program flow.
  3. Modifying Programs at Run-Time:
    gdb enables you to make changes to your program while it is running, offering a dynamic way to test fixes and alterations.

Downsides of Using gdb

  • Increased Disk Space Usage:
    The debug information required by gdb can significantly increase the size of your binaries, consuming more disk space.
  • Slower Execution Time:
    Programs run more slowly under gdb due to the additional overhead of debugging information and checks.

Setting Up gdb for OpenFOAM

To use gdb with your own solver or library in OpenFOAM, you need to modify the Make/options file to include the necessary debugging flags:

EXE_INC = -O0 -fdefault-inline -ggdb -DFULLDEBUG

This configuration ensures that your code is compiled with debugging information, disabling optimizations (-O0) to make the debugging process more straightforward and effective. By using these settings, you can leverage gdb to gain a deeper understanding of your code’s execution and address any issues more effectively.

Visual Studio Code for OpenFOAM Development

Visual Studio Code (VS Code) is a multi-platform Integrated Development Environment (IDE) available for Windows, macOS, and Linux. It is also well-suited for OpenFOAM development due to its extensive features and support for various programming languages.

Key Features of Visual Studio Code

  1. Multi-Platform Support:
    VS Code runs on Windows, macOS, and Linux, making it a flexible choice for developers working in different environments.
  2. Open Source Variant:
    VSCodium is an open-source version of VS Code that comes without telemetry, offering a more privacy-focused option. However, not all extensions of VSCode work with VSCodium.
  3. Supported Languages:
    VS Code supports a wide range of programming languages, including C, C#, C++, JavaScript, Julia, Perl, and Rust, among others. This makes it a comprehensive tool for diverse development needs.
  4. Syntax Highlighting and Auto-Completion:
    These features enhance coding efficiency and accuracy by providing visual cues and code suggestions.
  5. Revision Management:
    Integrated version control supports Git and other source control systems, facilitating efficient code management and collaboration.
  6. Graphical Debugging:
    VS Code offers powerful debugging capabilities with a graphical interface, making it easier to set breakpoints, inspect variables, and control code execution flow.

Qt Creator for OpenFOAM Development

Qt Creator is a cross-platform C++, JavaScript, Python and QML integrated development environment which simplifies GUI application development.

Key Features of Qt Creator

  1. Multi-Platform Support:
    Qt Creator runs on Windows, macOS, and Linux, providing flexibility for developers working across different operating systems.
  2. Integration with Qt Framework:
    Qt Creator is based on and integrated with the Qt framework, offering a robust environment for developing applications with rich user interfaces.
  3. Supported Languages:
    Qt Creator supports a variety of programming languages, including C++, Java, Markdown, JavaScript, Python, and QML. This wide range of language support makes it suitable for diverse development tasks.
  4. Syntax Highlighting and Auto-Completion:
    These features help improve coding efficiency and reduce errors by providing visual cues and code suggestions as you type.
  5. Revision Management:
    Integrated version control supports Git and other source control systems, allowing for efficient code management and collaboration.
  6. Graphical Debugging:
    Qt Creator includes powerful graphical debugging tools, enabling developers to set breakpoints, inspect variables, and control the execution flow of their applications visually.

By utilizing the comprehensive features of Qt Creator, developers can enhance their productivity and streamline the development and debugging process in OpenFOAM projects.

Author

Patrik Höhn

References

 

A more permanent version to this article with updates and fixes can be found at https://gitlab-ce.gwdg.de/hpc-team-public/science-domains-blog

Kategorien

Archive

--