Exploring Openfoam Source Code: There and Back Again

Exploring OpenFOAM source code:
There and back again.

Martin Beaudoin
IREQ, Hydro-Québec’s Research Institute
Chalmers OpenFOAM course: Guest presentation March 28th 2008

Three different facets of the same information
 C++ Classes definitions
 How to navigate the C++ class definitions using Doxygen
 Directory and file structure

 How to navigate and find information efficiently using Unix
commands.
 Evolution through time

 How to navigate the file revision history using revision
control tools.
2
Navigating the OpenFOAM class maze:
 Doxygen:
 Documentation system for C++, Java, Python, C, etc.
 Generates:
– On-line documentation in HTML from C++ source code
– Inheritance Class diagram
– Collaboration class diagram
– Hyperlinks so you can navigate swiftly through the class hierarchy
– Hyperlinks to the actual source code class definition (.H files)
– Search facility available if using a Web server (PHP script)
 OpenFOAM 1.4.1: HTML documentation available on-line:

– http://foam.sourceforge.net/doc/Doxygen/html/
 The configuration files for generating your own local copy of the
Doxygen documentation is also available
– $WM_PROJECT_DIR/doc/Doxygen/
3
A quick overview of OpenFOAM Doxygen doc: (1/14)
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Modifying the generated documentation:
 It is possible to customize the Doxygen
documentation:
 Changing the default settings chosen by OpenCFD
 Adding new information (side panel, etc.)
 Adding your own C++ classes
 These are the basic tools you need:

 Files from $WM_PROJECT_DIR/doc/Doxygen:
– Allwmake
– Doxyfile (for doxygen 1.5.1)
– Doxyfile.1.3.5 (for doxygen 1.3.5)
– FoamHeader.html, FoamFooter.html, Doxygen.css
 Unix commands:
– doxygen, doxywizard, dot
 Enough disk space:
– ~300 MB
18
Preparing our new documentation sandbox
19
Adapting for the available version of doxygen
20
Modifying Doxyfile : the hard way
21
Modifying Doxyfile : using doxywizard
22
Doxywizard : loading a configuration file
23
Doxywizard : Wizard mode
24
Doxywizard : Expert mode (1/9)
25
26
27
28
29
30
31
32
33
Doxywizard : Saving your modifications
34
Doxywizard : Generating the HTML files
A common mistake: the OF environment is not initialized...
35
Doxywizard : Generating the HTML files (take 2)
• 23 minutes on remote3.
• 241MB of data
36
Doxygen: Generating from the command line
37
Doxygen: Browsing the end result (Class Index)
38
Doxygen: Browsing the end result (Class Reference)
39
Doxygen: Browsing the end result: one limitation
40
Using Doxygen for your own development
 Create a separate directory for the new documentation
 Start from a pre-initialized Doxyfile
 Customize the Doxygen configuration:
 Change the name of the project
 Add the path to your library source code
 Keep only the libraries from OpenFOAM that you need
– Check your Make/options file for the list of needed libraries
 Customize as you see fit
 An example:
 Library OpenFoamTurbo from openfoam-extend
 http://openfoamwiki.net/index.php/Sig_Turbomachinery_Library_OpenFoamTurbo
41
Doxygen: Setup for library OpenFoamTurbo
42
Doxygen: Configuration for OpenFoamTurbo (1/5)
43
44
45
46
47
OpenFoamTurbo: Browsing the result (1/3)
48
49
50
Doxygen: some possible improvements (1/5)
51
52
53
54
• inherited member functions listed
• mixed blessing...
55
Doxygen: some useful pointers
 Main Web site:

 http://www.stack.nl/~dimitri/doxygen/index.html
 The Doxygen manual:

 http://www.stack.nl/~dimitri/doxygen/manual.html
 Helping Doxygen grab the comments in your source

code:
 http://www.stack.nl/~dimitri/doxygen/docblocks.html
56
OpenFOAM overall directory structure
$WM_PROJECT_DIR $WM_PROJECT_USER_DIR
applications/ applications/
bin/ lib/
doc/ run/
lib/
src/
tutorials/
wmake/
57
OpenFOAM useful shell aliases
 OpenFOAM provides useful predefined shell aliases:
 alias foam='cd $WM_PROJECT_DIR'
 alias run='cd $FOAM_RUN'
 alias tut='cd $FOAM_TUTORIALS'
 alias app='cd $FOAM_APP'
 alias src='cd $FOAM_SRC'
 etc., etc.
 You can also define your own aliases:

 alias doc='cd $WM_PROJECT_DIR/doc'
 alias of_1.4.1='. /chalmers/sw/unsup64/OpenFOAM/OpenFOAM-1.4.1/.OpenFOAM-1.4.1/bashrc'
 alias of_1.4.1-dev='. /chalmers/sw/unsup64/OpenFOAM/OpenFOAM-1.4.1-dev/.OpenFOAM-1.4.1-dev/bashrc'
 We can now move directly and quickly to some of the

major OpenFOAM directories.
58
Navigating a Unix file tree efficiently :
 Moving around OF file tree can be quite a typing exercise:
 cd src/finiteVolume/interpolation/surfaceInterpolation/multivariateSchemes/multivariateSurfaceInterpolationScheme
 bash/tcsh auto-completion helps a lot:

 cd s[TAB]fi[TAB]in[TAB]su[TAB]mu[TAB]mu[TAB]u[TAB]
 Moving around while leaving a trail:

 pushd : change directory, but remember where you came from
 popd: move back to previous directory memorized by pushd
 dirs: display the list of remembered directories
 popd/pushd/dirs implement a FILO (First In Last Out) stack of directories that

help you navigate efficiently in and out of a deep file tree
 man tcsh or man bash for more details
59
Navigating efficiently : pushd/popd examples
 Commands:  Current Directory:  Directory stack:
$> foam $WM_PROJECT_DIR $WM_PROJECT_DIR
$> dirs
$> pushd /tmp /tmp $WM_PROJECT_DIR

$> dirs /tmp
$> pushd ~ $HOME $WM_PROJECT_DIR

$> dirs /tmp
$HOME
$> popd /tmp $WM_PROJECT_DIR

$> dirs /tmp
$> popd $WM_PROJECT_DIR $WM_PROJECT_DIR

$> dirs
60
Navigating efficiently : pushd and aliases??
 A little quiz...
 How do you combine aliases like 'src' or 'app' with pushd/popd?
61
Navigating efficiently : pushd and aliases??
 A little quiz...
 How do you combine aliases like 'src' or 'app' with pushd/popd?
$> pushd . # memorize where we are

$> src # move to $FOAM_SRC
$> cd finiteVolume
$> .... do some browsing, etc. ...
$> popd # back where we were before pushd
62
Finding files:
 find:
 find $FOAM_SRC -iname \*fixedValue\*.[CH]
 locate:
 useful command to search through predefined file systems on a
Unix workstation.
– pre-digested, file system wide, “find” results stored in a database
– very quick search time
• example: locate -i doxygen
– man locate for more details
63
Finding files, one library at time:
 lnInclude directory:
 Available for every OpenFOAM library
 Created and updated automatically by wmake
 Provides, under a single roof, a quick access to all the files

needed to compile a given library
 Basic Unix commands do apply to symbolic links too:

– grep, find, more, etc.
 Editing a symbolic link == editing the actual file

– vi $FOAM_SRC/finiteVolume/lnInclude/cyclicFvPatch.H
– vi $FOAM_SRC/finiteVolume/fvMesh/fvPatches/constraint/cyclic/cyclicFvPatch.H
64
Searching inside files:
 Example: where is the definition of VSMALL

 grep:
 grep -i vsmall $FOAM_SRC/finiteVolume
– nothing interesting...
 find and grep:
 find $FOAM_SRC -iname \*.[CH] | xargs grep VSMALL
– too much information...
 find and grep, but filtering out some information:

 find $FOAM_SRC -iname \*.[CH] | xargs grep VSMALL | grep -v lnInclude | grep const
1:Same as previous command

2:Exclude results from lnInclude
3: Show only the constant definitions

NB: xargs: very useful command
65
Modifying files: keeping track of versions
 Using a Revision Control System helps you keep track of your
file modifications through time.
 copy file1.C file1.C.backup
– obvious limitations, but better than nothing
 RCS:
– Usually available and pre-installed on most Unix systems.
– Basic functionality. Per directory archive
– ci, co, rcsdiff
– A nice introduction:
• https://agave.garden.org/~aaronh/rcs/tichy1985rcs/html/
 Subversion for team collaboration

– http://en.wikipedia.org/wiki/Subversion_(software)
 International collaboration: openfoam-extend on SourceForge.net :

– http://openfoam-extend.wiki.sourceforge.net/
– http://openfoam-extend.svn.sourceforge.net/viewvc/openfoam-extend/
66
Browsing revisions from a Subversion repository (1/5)
67
68
69
70
71
How to get help
 OpenFOAM Forum
 http://openfoam.cfd-online.com/cgi-bin/forum/discus.cgi
 Try searching the Forum first!
– Your answer might already be there
 OpenFOAM Wiki
 http://openfoamwiki.net/index.php/Main_Page
 How-To do things:
– http://openfoamwiki.net/index.php/Main_HowTos
72

Exploring Openfoam Source Code: There and Back Again

Uploaded by

Copyright:

Available Formats

Exploring Openfoam Source Code: There and Back Again

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Exploring Openfoam Source Code: There and Back Again

Uploaded by

Copyright:

Available Formats

Exploring OpenFOAM source code:

There and back again.

Chalmers OpenFOAM course: Guest presentation March 28th 2008

 Directory and file structure

 Evolution through time

 OpenFOAM 1.4.1: HTML documentation available on-line:

 These are the basic tools you need:

A common mistake: the OF environment is not initialized...

• inherited member functions listed

 Main Web site:

 The Doxygen manual:

 Helping Doxygen grab the comments in your source

 You can also define your own aliases:

 We can now move directly and quickly to some of the

 bash/tcsh auto-completion helps a lot:

 Moving around while leaving a trail:

 popd/pushd/dirs implement a FILO (First In Last Out) stack of directories that

$> pushd /tmp /tmp $WM_PROJECT_DIR

$> pushd ~ $HOME $WM_PROJECT_DIR

$> popd /tmp $WM_PROJECT_DIR

$> popd $WM_PROJECT_DIR $WM_PROJECT_DIR

$> pushd . # memorize where we are

 Created and updated automatically by wmake

 Provides, under a single roof, a quick access to all the files

 Basic Unix commands do apply to symbolic links too:

 Editing a symbolic link == editing the actual file

 Example: where is the definition of VSMALL

 find and grep, but filtering out some information:

1:Same as previous command

3: Show only the constant definitions

 Subversion for team collaboration

 International collaboration: openfoam-extend on SourceForge.net :

You might also like

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.