Chalmers University of Technology

Fabian Peng Kärrholm

Why did my program crash?

or

How to debug your OpenFOAM codes using GDB

Chalmers University of Technology

Fabian Peng Kärrholm

Running your code

Coding your own software – good & bad

Programming your own codes without bugs is near impossible

even for Weller & Jasak

Chalmers University of Technology

Fabian Peng Kärrholm

Debugging your code

Debugging is a necessary evil to resolve bugs and examine crashes when developing all codes, and OpenFOAM is not an exception

Built-in debug feature shows more details, but gives only “passive” information

Chalmers University of Technology

Fabian Peng Kärrholm

Debugging your code – built-in

Debugflags available in .OpenFOAM-1.4.1/controlDictlduMatrix 2;

Will give output for each matrix-iteration:DICPCG: Iteration 475 residual = 0.542126

No Recompilation of code needed.

Flags set in code by:defineTypeNameAndDebug(PCG, 0);

Chalmers University of Technology

Fabian Peng Kärrholm

Debugging your code

Alternative way:

Inserting

Info << "U is " << U[celli] << endl;

Requires Re-compilation (usually many times)

Chalmers University of Technology

Fabian Peng Kärrholm

GDB - Introduction

GDB is the GNU project debugger

It can be used for

- Programs written in C, C++, Ada, Pascal etc

- Run & Stop at specific positions

- Examine variables at run-time

- Change your program at run-time

Chalmers University of Technology

Fabian Peng Kärrholm

You need to recompile… EVERYTHING!

Debug version of OpenFOAM requires 1 Gb of diskspace, vs 64 Mb for Opt

It is also slower

Even slower when run with GDB…

You need to recompile…

Before we start – Bad news

Chalmers University of Technology

Fabian Peng Kärrholm

Compiling with DebugFile: .OpenFOAM-1.4.1/bashrc

Commentsetenv WM_COMPILE_OPTION OptUncommentsetenv WM_COMPILE_OPTION Debug

Then run the Allwmake script and go for a very long break.When you're back, some packages (e.g. the paraview reader)

will have failed…

Chalmers University of Technology

Fabian Peng Kärrholm

Compiling with Debug

These packages can be compiled seperately with debug flags

Quick Solution:

Use the Opt version, as we're most likely not interested in debugging such packages

Done by simple copy of libPackageName.so

Chalmers University of Technology

Fabian Peng Kärrholm

Setup on Student Installation

Pre-compiled version of Debug done by Håkan

Used by copying

.OpenFOAM-1.4.1 from local installation to

/chalmers/users/userdir/

And editing .cshrc/.bashrc like described before

Chalmers University of Technology

Fabian Peng Kärrholm

First Debug

Objective: To find out what a part of the code does

Code: icoFoam - for incompressible, laminar flow

Simple code, suitable to start debugging, as there are not that many files included.

Chalmers University of Technology

Fabian Peng Kärrholm

Example – icoFoam

73: U = rUA*UEqn.H();74: phi = (fvc::interpolate(U) & mesh.Sf())

+ fvc::ddtPhiCorr(rUA, U, phi);77: adjustPhi(phi, U, p);

79: for (int nonOrth=0; nonOrth<=nNonOrthCorr; nonOrth++) { fvScalarMatrix pEqn ( fvm::laplacian(rUA, p) == fvc::div(phi) );

What does adjustPhi do?

Chalmers University of Technology

Fabian Peng Kärrholm

Example - icoFoam

Start GDB in case directory:gdb icoFoam

GNU gdb 6.5 ...

(gdb)

Start off by inserting a breakpoint where we want to inspect the code

b icoFoam.C:77

Chalmers University of Technology

Fabian Peng Kärrholm

Starting the Debug

Program can be started in two ways:start <root> <case> - Stops at main

or

run . . - Runs ProgramIf all is well, program should now stop at line 77 of icoFoam:

Breakpoint 1, main (argc=3, argv=0x7fffc346b128) at icoFoam.C:77

77 adjustPhi(phi, U, p);

Chalmers University of Technology

Fabian Peng Kärrholm

Two Ways of Stepping

Next [n] – Step until next line in the current program, will not debug functions and included files

Step [s] – Step until next source line, will debug subfunctions

Both commands can be followed by a number to step a certain amount of lines

Chalmers University of Technology

Fabian Peng Kärrholm

adjustPhi

where – shows which file we are debugging and which file called it

list – gives a listing of the source code around the current line, e.g. list 40,60 lists lines 40-60

Now in:cfdTools/general/adjustPhi/adjustPhi.C:42

Stepping and listing the code will show how adjustPhi ensures continuity

Chalmers University of Technology

Fabian Peng Kärrholm

Useful Commands

See GDBCommands.pdf for a quick guide to the commands available in GDB. This list is by no means complete and a full listing is available at:

http://sourceware.org/gdb/documentation/

Chalmers University of Technology

Fabian Peng Kärrholm

Tutorial Example

Why does Xoodles crash when starting the pitzDaily3D case?

Known error from forums, output from Opt:#6 main in

"/c3se/users/f98faka/OpenFOAM/OpenFOAM-1.4.1/applications/bin/linux64GccDPOpt/Xoodles"

#7 __libc_start_main in "/lib64/tls/libc.so.6"

With Debug version of OF:#7 main at ~/OpenFOAM/OpenFOAM-1.4.1/applications/solvers/combustion/Xoodles/../XiFoam/bEqnn.H:79#8 __libc_start_main in "/lib64/libc.so.6"

Chalmers University of Technology

Fabian Peng Kärrholm

Tutorial Example

Start Xoodles with GDB and a breakpoint at this location:

Breakpoint 1, main (argc=3, argv=0x7fffb8830fc8) at ../XiFoam/bEqn.H:79

79 volScalarField tauEta = sqrt(thermo->muu()/(rhou*epsilon));

Possible issue with division, inspection of some epsilon values shows low epsilon.

Chalmers University of Technology

Fabian Peng Kärrholm

Questions GDB can answer

- What does .flux do?

- What happens when .solve is issued?

- When does my variable go below x?

- How does scheme x work?

- Where did my code crash?

Chalmers University of Technology

Fabian Peng Kärrholm

End

Thanks for listening!