The Three Main OpenFOAM Variants

1. OpenFOAM Foundation

Developer: The OpenFOAM Foundation, with development by CFD Direct Current Version: OpenFOAM v13 (released July 2025) Release Schedule: Annual releases Website: openfoam.org

The OpenFOAM Foundation distributes OpenFOAM exclusively as free and open source software under the General Public License (GPL) v3. This version is developed by CFD Direct and released through The OpenFOAM Foundation, a not-for-profit organization.

Key Features:

• Ownership: The Foundation owns the copyright of the code it distributes
• Development Focus: Emphasizes robustness, usability, and extensibility
• Numbering System: Uses sequential numbering (v1, v2, v3… v13)
• Academic Preference: More commonly used in academia
• Recent Improvements: Version 13 includes rewritten mesh zones, field-based Lagrangian improvements, enhanced MULES algorithm, and better visualization support

2. ESI-OpenCFD

Developer: OpenCFD Ltd (wholly owned subsidiary of ESI Group, now part of Keysight Technologies) Current Version: OpenFOAM v2506 (released June 2025) Release Schedule: Bi-annual releases (June and December) Website: openfoam.com

This version is maintained by ESI-OpenCFD and has been the commercial fork since 2016. OpenCFD Ltd owns the OpenFOAM trademark.

Key Features:

• Trademark Owner: OpenCFD Ltd owns the registered OpenFOAM trademark
• Numbering System: Uses year-month format (v2506 = June 2025)
• Industry Focus: More commonly used in industry
• Advanced Features: Includes overset meshing capabilities not available in the Foundation version
• Frequent Updates: Releases every six months with extensive quality assurance testing
• Professional Support: Backed by Keysight’s worldwide infrastructure and support services

3. foam-extend

Developer: Community-backed fork maintained by Wikki Ltd Current Version: foam-extend 5.0 Website: foam-extend project on SourceForge

foam-extend is a community-driven fork that diverged from the main OpenFOAM development line, focusing on preserving and extending advanced features.

Key Features:

• Community-Driven: Open project welcoming contributions from all users and developers
• Extended Functionality: Contains features that were removed from other OpenFOAM versions
• Specialized Applications: Strong focus on fluid-structure interaction, turbomachinery, and advanced CFD features
• Different Architecture: Uses different naming conventions and setup procedures compared to other versions
• Advanced Features: Includes general grid interpolation (GGI), block-coupled matrix support, comprehensive dynamic mesh capability, and finite area methods

Historical Development

The complex history of OpenFOAM development explains the current fragmentation:

1. 1989: Henry Weller creates “FOAM” at Imperial College London
2. 2004: OpenFOAM released as open source by OpenCFD Ltd
3. 2011: OpenCFD acquired by SGI; OpenFOAM Foundation created to hold copyright
4. 2012: OpenCFD acquired by ESI Group
5. 2014: Henry Weller and Chris Greenshields leave ESI to form CFD Direct
6. 2016: OpenCFD begins releasing its own version directly (v1606+)
7. 2024: ESI OpenCFD becomes part of Keysight Technologies

Key Differences Summary

Which Version to Choose?

The choice depends on your specific needs:

• Students and General Learning: Any version works well, but Foundation version may be preferable for academic use
• Advanced Features: Check specific capabilities - ESI version for overset meshes, foam-extend for fluid-structure interaction
• Industry Applications: ESI version often preferred for commercial applications
• Research: Consider foam-extend if you need specialized advanced features that were removed from other versions

All three versions maintain compatibility with standard OpenFOAM solvers and cases, though some differences exist in advanced features and specific implementations.

Let’s compare two common ways to represent a matrix in C++: std::vector<std::vector<double>> and a single, flattened std::vector<double>. While the former is often more intuitive, the latter is orders of magnitude faster. Understanding why requires us to look past the C++ abstraction and think like the hardware.

The Core of the Matter: The CPU Cache

Modern CPUs are incredibly fast, but main memory (RAM) is sluggish in comparison. To bridge this speed gap, CPUs use small, extremely fast caches (L1, L2, L3) located directly on the chip. When your program needs data from a memory address, the CPU doesn’t just fetch that single byte. It fetches the entire cache line, a fixed-size block, typically 64 bytes, that contains the requested address.

This is based on the principle of spatial locality: if you access a piece of data, you are highly likely to need the data located right next to it very soon.

Working in tandem with the cache is the hardware prefetcher, a smart assistant that monitors your memory access patterns. If it detects a simple, predictable pattern (like reading addresses one after another), it will proactively fetch the next cache lines it thinks you’ll need, hiding the latency of the slow trip to RAM.

The effectiveness of these two hardware components is entirely dependent on your choice of data structure.

The Cache Killer: std::vector<std::vector<T>>

This structure is an abstraction of a 2D matrix, but in memory, it’s anything but. It’s a vector of pointers, and each of those pointers leads to a completely separate, non-contiguous block of memory for each row.

Consider iterating through this matrix row by row:

• The loop for row 0 accesses data at memory region 0xAAAA.
• The loop for row 1 accesses data at memory region 0xBBBB.
• The loop for row 2 accesses data at memory region 0xCCCC.

From the hardware prefetcher’s perspective, the sequence of base addresses (0xAAAA, 0xBBBB, 0xCCCC) is random and unpredictable. It cannot guess where the next row is. As a result, every time your outer loop finishes one row and moves to the next, the CPU stalls. It must issue a new, slow request to main memory, resulting in a compulsory cache miss. You are guaranteed to pay the full price of memory latency on every single row transition.

The Prefetcher’s Best Friend: The Flattened std::vector<T>

Now, consider a single, contiguous vector where the matrix is stored row by row.

• Row 0 starts at address 0x10000.
• Row 1 starts at address 0x10000 + row_size_in_bytes.
• Row 2 starts at address 0x10000 + 2 * row_size_in_bytes.

This creates a perfectly linear, strided access pattern. This is the exact pattern the hardware prefetcher is designed to exploit. As your code nears the end of processing row 0, the prefetcher has already recognized the pattern and has started fetching the cache lines for row 1. When your code is ready for the next row, the data is already waiting in the cache. The CPU stall is avoided.

Beyond Raw Speed: The Architectural Wins

The benefits of a flat, contiguous data structure go far beyond the inner loop. Adopting this design is a fundamental architectural improvement.

1. Seamless Interoperability: A flat C-style array is the lingua franca of high-performance computing. Want to offload work to a GPU? cudaMemcpy requires a pointer to a contiguous block of memory. Need to interface with Python for analysis? You can create a NumPy array that is a zero-copy view into your C++ vector’s memory. Integrating with high-performance libraries like Eigen, OpenBLAS, or Intel MKL becomes trivial.

2. Dramatically Simplified Serialization: Saving and loading your data becomes incredibly simple and fast. Instead of complex, nested loops to write each small vector, you can write the entire data block with a single function call (file.write(vec.data(), vec.size() * sizeof(T))).

3. Reduced Memory Overhead: Every std::vector object has memory overhead (pointers to its start, end, and capacity). A vector<vector<T>> representing a large matrix could consist of thousands of individual std::vector objects, wasting memory and leading to memory fragmentation. A single flattened vector has the absolute minimum overhead.

The Takeaway

For a computational scientist, performance is a feature. While algorithmic complexity is crucial, it’s only half the story. True optimization requires a hardware-aware mindset. By choosing data structures that create predictable, linear access patterns, you align your code with the fundamental way CPUs are designed to work. You stop fighting the hardware and start letting its powerful caching and prefetching mechanisms work for you.

So the next time your code is mysteriously slow, don’t just look at the loops. Look at the memory.

Prerequisites

• Quarto installed on your system
• Git repository with your presentation files
• GitHub account

Project Structure

Your project should have this structure:

your-presentation/
├── presentation.qmd          # Your main presentation file
├── _quarto.yml              # Quarto configuration
├── assets/                  # Images, videos, etc.
│   ├── image1.png
│   ├── video1.mp4
│   └── ...
└── docs/                    # Generated output (created by Quarto)
    ├── index.html
    ├── presentation.html
    └── ...

Step 1: Create Quarto Configuration File

Create a _quarto.yml file in your project root:

project:
  type: website
  output-dir: docs

website:
  title: "Your Presentation Title"
  site-url: "https://your-username.github.io/your-repo-name"
  
format:
  html:
    theme: default

Replace:

• Your Presentation Title with your actual presentation title
• your-username with your GitHub username
• your-repo-name with your repository name

Step 2: Create Your Presentation

Create a .qmd file (e.g., presentation.qmd) with your content:

---
title: "Your Presentation Title"
subtitle: "Your Subtitle"
author: "Your Name"
date: "2025-07-29"
format: 
  revealjs:
    theme: default
    slide-number: true
    chalkboard: true
    logo: your-logo.png
    footer: "Your Footer Text"
    title-slide-attributes:
      data-background-image: "background.svg"
      data-background-size: "auto"
      data-background-opacity: "0.3"
      data-background-position: "bottom"
---

## Slide 1
Your content here

## Slide 2
More content here

Step 3: Render Your Presentation

Run the following command in your project directory:

quarto render

This will:

• Generate HTML files in the docs/ directory
• Copy all assets (images, videos) to the output directory
• Create an index.html file for GitHub Pages

Step 4: Initialize Git Repository (if not already done)

git init
git add .
git commit -m "Initial commit"

Step 5: Push to GitHub

1. Create a new repository on GitHub
2. Add the remote origin:

   git remote add origin https://github.com/your-username/your-repo-name.git
   

3. Push your code:

   git push -u origin main
   

Step 6: Configure GitHub Pages

1. Go to your GitHub repository: https://github.com/your-username/your-repo-name
2. Click on “Settings” tab
3. Scroll down to “Pages” in the left sidebar
4. Under “Source”, select:
   • Source: “Deploy from a branch”
   • Branch: “main”
   • Folder: “/ (docs)”
5. Click “Save”

Step 7: Access Your Presentation

After a few minutes, your presentation will be available at:

• Main site: https://your-username.github.io/your-repo-name/
• Direct link: https://your-username.github.io/your-repo-name/presentation.html

Automatic Updates

To update your presentation:

1. Edit your .qmd file
2. Re-render: quarto render
3. Commit and push changes:

   git add .
   git commit -m "Update presentation"
   git push origin main
   

GitHub Pages will automatically update your site within a few minutes.

Troubleshooting

Common Issues

1. 404 Error:
   • Check that GitHub Pages is configured to serve from the correct branch and folder
   • Ensure index.html exists in the docs/ directory
2. Missing Assets:
   • Verify that all images/videos are in the correct relative paths
   • Check that Quarto copied all assets to the docs/ directory
3. Site Not Updating:
   • Wait a few minutes for GitHub Pages to update
   • Check the repository’s “Actions” tab for any deployment errors
   • Clear your browser cache
4. Relative Path Issues:
   • Use relative paths for all assets (e.g., ./image.png not /image.png)
   • Ensure the site-url in _quarto.yml matches your GitHub Pages URL

Useful Commands

# Preview locally before deploying
quarto preview

# Render specific file
quarto render presentation.qmd

# Check Quarto version
quarto --version

# Validate Quarto project
quarto check

Resources

• Quarto Documentation
• GitHub Pages Documentation
• RevealJS Documentation
• Quarto Presentations Guide

The Challenge: Integrating an Optional Dependency

Tracy is a powerful, frame-by-frame profiler that requires code to be manually annotated (or “instrumented”) to measure the execution time of specific scopes. The most direct method of integration is to include the main Tracy header and use its macros within the functions of interest.

For example, to profile the Predict_MLP function in CDataDrivenFluid.cpp, one could do the following:

1. Add an include directive for the Tracy header:

   #include <tracy/Tracy.hpp>
   

2. Insert the annotation macro at the beginning of the target function:

   void CDataDrivenFluid::Predict_MLP(...) {
       ZoneScopedN("Predict_MLP"); // Tracy annotation
       // ... function logic ...
   }
   

While this approach is functionally correct, it presents significant challenges in the context of a large, collaborative project like SU2. The primary issue is that Tracy is an optional dependency. Not all developers will have it installed, and it should not be required for a standard build. This direct integration method would cause compilation to fail for any user who has not explicitly set up the Tracy library.

This necessitates a more robust solution that allows for the feature to be enabled or disabled at compile time.

The Role of the C++ Preprocessor

The C++ preprocessor is a tool that parses source code and processes instructions (known as directives) before the code is passed to the compiler. While commonly used for including headers (#include), it also provides powerful capabilities for conditional compilation.

Three directives are key to our solution:

1. #define: This directive is used to define a macro, which is essentially a named fragment of code. The preprocessor will substitute the macro’s name with its defined value throughout the code.

2. #ifdef <macro>: This checks if a given macro has been defined. This is typically done via a compiler flag (e.g., g++ -D<macro>).

3. #else and #endif: These work with #ifdef to create conditional blocks, allowing the preprocessor to include or ignore sections of code based on the defined macros.

By combining these directives, we can instruct the preprocessor to alter the source code based on the build configuration, effectively including or removing the Tracy annotations before the compiler even sees them.

The Solution: A Centralized Wrapper Header

To manage the optional integration cleanly, we can create a single, centralized header file—a “wrapper”—that contains all the logic for the Tracy integration. This practice isolates the third-party dependency and provides a consistent interface for the rest of the project.

We created the file tracy_structure.hpp with the following content:

// /home/divyaprakash/SU2/Common/include/tracy_structure.hpp

#pragma once

// Check if the TRACY_ENABLE macro has been defined by the build system.
#ifdef TRACY_ENABLE
  // If defined, the project is being compiled with profiling enabled.

  // 1. Include the actual Tracy header to make its functionality available.
#  include "tracy/Tracy.hpp"

  // 2. Define project-specific macros as aliases for the real Tracy macros.
#  define SU2_ZONE_SCOPED ZoneScoped
#  define SU2_ZONE_SCOPED_N(name) ZoneScopedN(name)

#else
  // If not defined, the project is being compiled without profiling.

  // 1. Do NOT include the Tracy header.

  // 2. Define the project-specific macros as empty statements.
#  define SU2_ZONE_SCOPED
#  define SU2_ZONE_SCOPED_N(name)

#endif // End of the conditional compilation block.

This approach has several key advantages:

• Modularity: All logic related to Tracy is contained within this single file.
• Maintainability: If the project ever moves to a different profiler, only this wrapper file needs to be significantly modified.
• Robustness: The code now compiles successfully for all users, regardless of whether they have Tracy enabled. When disabled, the macros compile to nothing, incurring zero performance overhead.

Final Implementation

With the wrapper in place, the modification to the target source file, CDataDrivenFluid.cpp, becomes clean and maintainable.

Before:

#include <tracy/Tracy.hpp>
// ...
void CDataDrivenFluid::Predict_MLP(...) {
    ZoneScopedN("Predict_MLP");
    // ...
}

After:

#include "../../../Common/include/tracy_structure.hpp" // Include the wrapper
// ...
void CDataDrivenFluid::Predict_MLP(...) {
    SU2_ZONE_SCOPED_N("Predict_MLP"); // Use the project-specific macro
    // ...
}

This implementation successfully integrates the Tracy profiler while adhering to best practices for software engineering in a large-scale C++ project. By leveraging the preprocessor to create a centralized wrapper, we ensure that the addition of this optional feature does not compromise the stability or cleanliness of the core codebase.

SU2 is an open-source computational fluid dynamics (CFD) software suite widely used by researchers and engineers to simulate complex fluid flow problems. As part of my Google Summer of Code (GSoC) project, I am focused on improving the MLPCpp submodule within SU2, which integrates machine learning techniques to enhance CFD simulations. To achieve meaningful performance improvements, I required a profiling tool capable of providing detailed insights into execution time and resource utilization. While Valgrind is a well-known profiler, its significant overhead makes it less suitable for large-scale simulations. This led me to adopt Tracy, a real-time, nanosecond-resolution profiler with minimal overhead and an intuitive interface. In this blog post, I outline the process of integrating Tracy with SU2 and demonstrate its application in profiling my GSoC work.

What is Tracy?

Tracy is a high-performance profiler designed for C++ applications, offering real-time profiling with exceptionally low overhead. Unlike Valgrind, which can drastically slow down execution, Tracy is optimized for use in production environments, making it ideal for performance analysis in computationally intensive applications like SU2. Key features include:

• Real-time visualization of profiling data.
• Nanosecond-resolution timing for precise measurements.
• Customizable instrumentation for targeted profiling.
• A graphical user interface (GUI) for analyzing results.

For a deeper dive into Tracy’s capabilities, refer to the Tracy documentation.

Setting Up Tracy with SU2

Integrating Tracy with SU2 involves three main steps: installing the client, setting up the server, and instrumenting the code. Below, I detail the process based on my setup: Ubuntu 22.04.5 LTS, SU2 v8.2.0 (“Harrier”), Meson build system (≥0.61.1), and Git.

Client Installation

The “client” refers to the Tracy library embedded within the SU2 executable, responsible for collecting profiling data during runtime. To integrate it into SU2 using Meson, follow these steps:

1. Create a wrap file for Tracy:
   • Navigate to the SU2 directory: cd SU2.
   • Create a file named subprojects/tracy.wrap with the following content:

     [wrap-git]
     url = https://github.com/wolfpld/tracy.git
     revision = master
     depth = 1
     

2. Update Meson options:
   • Edit meson_options.txt (or meson.options) to add:

     option('tracy_enable', 
            type: 'boolean', 
            value: false, 
            description: 'Enable Tracy profiling support')
     

3. Modify the main Meson build file:
   • In meson.build, add Tracy as a dependency when enabled:

     if get_option('tracy_enable')
         tracy_dep = dependency('tracy', static: true)
         su2_deps += tracy_dep
         su2_cpp_args += '-DTRACY_ENABLE'
              
         if get_option('buildtype') != 'debugoptimized'
             warning('For optimal Tracy profiling, use --buildtype=debugoptimized')
         endif
     endif
     

   • Update the default options at the top:

     default_options: ['buildtype=release',
                       'warning_level=0',
                       'c_std=c99',
                       'cpp_std=c++11',
                       'tracy_enable=false']
     

   • Update the Build Summary To display whether Tracy support is enabled in the terminal summary, modify the format string at the end of meson.build: Insert the get_option('tracy_enable') as shown below:

     '''.format(get_option('prefix')+'/bin', meson.project_source_root(), get_option('enable-tecio'), get_option('enable-cgns'),
              get_option('enable-autodiff'), get_option('enable-directdiff'), get_option('enable-pywrapper'), get_option('enable-mkl'),
              get_option('enable-openblas'), get_option('enable-pastix'), get_option('enable-mixedprec'), get_option('enable-librom'),
              get_option('enable-coolprop'), get_option('enable-mlpcpp'), get_option('tracy_enable'),
              meson.project_build_root().startswith(meson.project_source_root()) ? meson.project_build_root().split('/')[-1] : meson.project_build_root())
     

     Insert this line into the summary format string:-

     Tracy Profiler: @14@
     

     Replace the existing install line with:

     Use './ninja -C @15@ install' to compile and install SU2
     

4. Build SU2 with Tracy:
   • Tracy project requires meson version >=1.3.0, however the version of meson provided by SU2 is much lower. Thus it needs to be manually installed.

     pip install --user --upgrade meson
     

   • Run the preconfigure script since we are not using the provided meson.py script in the SU2 directory

     ./preconfigure.py 
     

   • ninja must also be installed manually since we are skipping the use of meson.py

     sudo apt install ninja-build 
     

   • Configure and build SU2:

     meson setup build_tracy -Dwith-mpi=disabled -Denable-mlpcpp=true --buildtype=debugoptimized -Dtracy_enable=true --prefix=/home/user/SU2_install
     ninja -C build_tracy install
     

   • Adjust the --prefix path to your desired installation directory.

This process embeds the Tracy client into SU2, preparing it for profiling.

Server Installation

The “server” is the Tracy profiler application that visualizes the data collected by the client. To set it up:

1. Install dependencies:
   • On Ubuntu, install the required libraries:

     sudo apt install libfreetype6-dev libcapstone-dev libdbus-1-dev \
     libxkbcommon-dev libwayland-dev wayland-protocols \
     libegl1-mesa-dev libglvnd-dev \
     libgtk-3-dev
     

2. Build the Tracy profiler:
   • Navigate to the Tracy directory: cd ~/SU2/subprojects/tracy.
   • Use CMake to build the profiler:

     cmake -B profiler/build -S profiler -DCMAKE_BUILD_TYPE=Release -DLEGACY=ON
     cmake --build profiler/build --config Release --parallel
     

   • Note: I used -DLEGACY=ON for X11 support due to compilation issues with Wayland, though this is not the recommended approach.

The Tracy server is now ready to visualize profiling data.

Instrumenting the Code

To gather useful profiling data, the SU2 code must be instrumented with Tracy macros. For my GSoC project, I focused on profiling the Predict_MLP function in the CDataDrivenFluid class. Here’s how to do it:

1. Include the Tracy header:
   • Add at the top of the source file:

     #include <tracy/Tracy.hpp>
     

2. Add profiling macros:
   • Instrument the function with ZoneScopedN:

     unsigned long CDataDrivenFluid::Predict_MLP(su2double rho, su2double e) {
         ZoneScopedN("Predict_MLP");
         unsigned long exit_code = 0;
         // Function implementation
         return exit_code;
     }
     

   • The ZoneScopedN("name") macro labels the profiling zone, making it identifiable in the Tracy GUI.

Repeat this process for other functions or sections you wish to profile.

Using Tracy for Profiling

With the client and server set up and the code instrumented, profiling SU2 is straightforward:

1. Launch the Tracy profiler:
   • Navigate to the profiler build directory:

     cd ~/SU2/subprojects/tracy/profiler/build
     

   • Run the profiler:

     ./tracy-profiler
     

   • Click “Connect” in the GUI; it will wait for a connection from SU2.
2. Execute the instrumented SU2 simulation:
   • In a separate terminal, navigate to your simulation directory and run:

     /home/user/SU2_install/bin/SU2_CFD config_NICFD_PINN.cfg
     

   • Replace the path and configuration file as needed.

As the simulation runs, Tracy displays real-time profiling data. The GUI allows you to explore performance metrics, identify bottlenecks, and optimize code effectively.

Conclusion

Using Tracy to profile my SU2 code has been an important step in my GSoC project. Its low overhead and real-time visualization have enables me to pinpoint performance issues with precision. By following the steps outlined above, you can integrate Tracy into your own SU2 projects and leverage its capabilities for performance analysis. For advanced features and troubleshooting, consult the Tracy documentation. I also came across this blog, which served as a helpful starting point for understanding the Tracy profiler and getting it up and running.

To optimize performance in a large codebase like SU2, you must:

1. Identify performance bottlenecks using profiling tools.
2. Locate the exact function(s) consuming the most time.
3. Understand their internals using call graphs.
4. Micro-measure time-critical regions.
5. Apply improvements and verify the impact.

This post focuses on profiling and visualizing the call graph using valgrind and kcachegrind.

Introduction

When working on performance-critical applications like SU2, identifying and addressing bottlenecks is essential. While this blog uses SU2 as the context, the process discussed here is applicable to most large C++ projects.

Profiling with gprof

SU2 supports profiling via gprof. To enable it, compile SU2 with -Denable-gprof=true.

./meson.py build_gsoc -Denable-pywrapper=true -Denable-mlpcpp=true -Denable-gprof=true --prefix=/home/divyaprakash/SU2_DP
 ./ninja -C build_gsoc install

Then run the desired executable normally:

/path/to/binary/SU2_CFD config.cfg

This generates a gmon.out file in the working directory. Analyze it using:

gprof /path/to/binary/SU2_CFD > analysis.txt

Interpreting the Output

In analysis.txt, the flat profile lists the most time-consuming functions:

time   seconds   seconds    calls  Ts/call  Ts/call  name    
  6  47.43      2.03     2.03                             MLPToolbox::CNeuralNetwork::Predict(std::vector<double, std::allocator<double> >&)

Here, MLPToolbox::CNeuralNetwork::Predict emerges as the top time consumer. However, it may not be straightforward to locate this function in the source code directly, especially in a large project like SU2.

Finding the Function in Source Code

To locate the function in context, use gdb:

gdb --args ~/SU2_DP/serial/bin/SU2_CFD config_NICFD_PINN.cfg
(gdb) break MLPToolbox::CNeuralNetwork::Predict
(gdb) run

This places a breakpoint and reveals the exact location of the function in the source code. In my case the following output was obtained which pointed to exact location.

Breakpoint 1, MLPToolbox::CNeuralNetwork::Predict (this=0x209d500, inputs=std::vector of length 2, capacity 2 = {...}) at ../SU2_CFD/src/fluid/../../include/fluid/../../../subprojects/MLPCpp/include/CNeuralNetwork.hpp:651

Going Beyond: Understanding the Call Graph

Profiling alone doesn’t reveal why a function is expensive. The time could be due to the function itself or its callees. While gprof is supposed to provide call graph information, it did not in this case—possibly due to function inlining or compiler optimizations, which are known to interfere with accurate profiling output.

This is where valgrind and kcachegrind come into picture.

Visualizing the Call Graph with Valgrind + KCachegrind

To analyze function calls and their time share:

valgrind --tool=callgrind ~/SU2_DP/serial/bin/SU2_CFD config_NICFD_PINN.cfg

This creates an output file such as callgrind.out.50464. You can visualize it with:

kcachegrind callgrind.out.50464

Interpreting the Call Graph

Using kcachegrind, we navigate the call graph and observe that the Predict function spends most of its time in two callees:

• ComputePsi
• ComputeChi

This pinpointed the actual performance bottleneck, enabling targeted optimization efforts.

Final Notes

While valgrind and kcachegrind are powerful tools for analyzing code structure and bottlenecks, they are not ideal for runtime performance measurements due to the overhead introduced. In future posts, I will explore tracy, a high-performance real-time profiler that provides detailed runtime metrics with minimal overhead.

To dig deeper into kcachegrind, refer to the official documentation.

Getting started with contributing to a large-scale open-source project can feel daunting—especially if you’re new to collaborative software development, C++, or tools like GitHub. This guide is intended for beginners, like myself, who are taking their first steps into this space, such as through Google Summer of Code (GSoC) or other contribution opportunities.

The practices and tools shared here will help you efficiently navigate large C++ projects, whether your goal is to fix documentation, add new features, or improve performance.

1. GitHub Workflow: Fork, Clone, Branch

To contribute to a GitHub-hosted project, start by forking the repository. This creates a personal copy where you can make changes safely.

Steps:

• Fork the repo from the GitHub website.

• Clone it to your local system:

  git clone https://github.com/your-username/project-name.git
  cd project-name
  

• Add the original repo as the upstream to keep your fork up to date:

  git remote add upstream https://github.com/original-owner/project-name.git
  

  This allows you to fetch updates later using:

  git fetch upstream
  git merge upstream/main  # or 'develop', depending on the repo
  

• Create a dedicated branch for your work:

  git checkout -b feature-branch
  git push -u origin feature-branch
  

Using -u links your local branch to the remote one, so future git push commands will automatically target the correct destination.

2. SSH Keys: Avoid Typing Credentials Every Time

GitHub recommends setting up SSH-based authentication for secure and password-free interaction.

Steps:

1. Generate a new SSH key:

   ssh-keygen -t ed25519 -C "your_email@example.com"
   

2. Add the private key to the agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   

3. Add the public key to GitHub:

   cat ~/.ssh/id_ed25519.pub
   

   Copy and paste this into GitHub > Settings > SSH and GPG keys.

If you cloned using HTTPS and want to switch to SSH:

1. Update the remote URL:

   git remote set-url origin git@github.com:your-username/project-name.git
   

2. Verify it:

   git remote -v
   

   It should now show the SSH URL:

   origin  git@github.com:your-username/project-name.git
   

Now git push will use SSH without prompting for credentials.

3. Choosing an Editor: Why I Recommend VS Code

While some experienced developers might opt for terminal-based editors like vim or emacs, I found Visual Studio Code (VS Code) to be a practical and user-friendly choice, especially when dealing with large C++ codebases.

Recommended Extensions:

• C/C++ (Microsoft): Provides IntelliSense and debugging support.
• CMake Tools: For configuring and building CMake-based projects.
• CodeLLDB or C++ GDB: Enables powerful in-editor debugging.
• GitLens: Adds powerful Git features inside VS Code.

4. Automating Builds with tasks.json

Instead of manually switching to a terminal and typing build commands each time, you can define build tasks in VS Code using tasks.json. This file allows you to run common shell commands from within the editor.

Example:

{
  "label": "Build Project",
  "type": "shell",
  "command": "ninja -C build install",
  "group": {
    "kind": "build",
    "isDefault": true
  }
}

This configuration builds your project using the ninja build system (or make, depending on your setup). You can trigger it by pressing Ctrl+Shift+B in VS Code.

Your provided tasks.json is set up to install the project after building it:

"command": "ninja -C build_serial install"

Adjust the build directory name as needed for different configurations.

5. Debugging with GDB and launch.json

For larger projects, simple print statements quickly become inefficient. A proper debugger helps you step through the code, inspect variables, and set breakpoints.

launch.json helps you:

• Specify the binary to debug.
• Pass runtime arguments (e.g., config files).
• Set the working directory.
• Choose GDB or LLDB as the backend.

Here’s a simplified version inspired by your setup:

{
  "name": "Debug Project",
  "type": "cppdbg",
  "request": "launch",
  "program": "${workspaceFolder}/build/bin/my_executable",
  "args": ["input.cfg"],
  "cwd": "${workspaceFolder}/test_cases/my_case",
  "stopAtEntry": false,
  "MIMode": "gdb",
  "externalConsole": false
}

This allows debugging directly within VS Code using breakpoints and variable inspection, without leaving the editor.

Your custom launch.json even supports debugging with MPI-enabled programs—this is very helpful for parallel simulations.

6. Profiling with gprof

After ensuring your code works, it’s useful to measure its performance. gprof is a lightweight tool for profiling C++ applications compiled with -pg.

Steps:

1. Compile with profiling enabled: Add -pg to both compile and link flags.

2. Run the program (avoid wrappers like Python when profiling):

   ./my_executable input.cfg
   

3. Analyze results:

   gprof ./my_executable gmon.out > analysis.txt
   

   This will generate a text file detailing function call times and frequencies, helping you identify bottlenecks.

7. Maintaining Multiple Builds

For robust development, maintain separate build directories for different purposes:

Use separate build directories (build_debug, build_release, build_profile) with different CMake options or toolchain files.

Final Thoughts

With this setup, you can:

• Organize your GitHub workflow.
• Edit and build efficiently within VS Code.
• Debug with breakpoints and variable inspection.
• Profile performance bottlenecks.
• Push changes back to your forked repository.

The next step in your contribution journey is to submit a pull request (PR)—a topic I’ll cover in a future post once I’ve gone through the process myself.

Introduction

When contributing to an open-source project that employs submodules, it is crucial to adopt a workflow that ensures contributions are effectively managed and integrated. This article outlines a recommended approach for contributing to a submodule within a larger repository, using the example of MLPCpp in the SU2 framework. It also includes technical steps for integrating modified submodules using symbolic links and Meson.

What Are Submodules?

In Git, a submodule is a repository embedded within another repository (the “superproject”). It allows a project to include and track an external repository at a specific commit. Submodules are commonly used when a project depends on external code but wants to maintain a fixed version or revision of that dependency.

For instance, in the SU2 project, MLPCpp is included as a submodule in the subprojects/MLPCpp directory. This means that SU2 references a specific commit of the MLPCpp repository, and updates to the submodule are controlled explicitly.

Key Considerations

When planning to modify MLPCpp, which is integrated as a submodule within SU2, an important question arises: Should the entire SU2 repository be forked, or should the fork be limited to the submodule (MLPCpp)?

Additionally, after installing and building SU2 (for example, using the Meson build system with -Denable-mlpcpp=true), it is natural to wonder whether modifications can be made directly within the submodule directory (subprojects/MLPCpp).

Recommended Approach

The recommended strategy is to fork and develop only the MLPCpp submodule, rather than the entire SU2 repository. This approach maintains clear version control boundaries and reduces the complexity of managing unrelated components.

Key steps include:

1. Fork the MLPCpp repository independently. This isolates changes to the specific component of interest, making them easier to test, manage, and contribute back to the upstream project.

2. Clone the forked MLPCpp repository locally and create a dedicated feature branch (it’s a best practice to keep the main branch of your fork clean and in sync with the upstream repository). This approach simplifies pulling updates from upstream, avoids merge conflicts, and provides a stable base for creating feature branches.

3. To integrate and test these changes within the SU2 environment, replace the submodule directory in SU2 with a symbolic link or configure Meson to use the local version of MLPCpp. This allows testing the modified MLPCpp code without impacting SU2’s main repository or its submodule configuration.

4. Once the changes have been verified, submit a pull request to the MLPCpp repository. This ensures that contributions are cleanly integrated into the upstream project.

Advantages of This Approach

• Clear version control: Isolating submodule changes avoids unintended modifications to the larger project and makes it easier to track specific contributions.
• Reduced risk of overwrites: Updates to the parent repository (SU2) will not overwrite changes made directly in the submodule directory.
• Streamlined collaboration: Contributing to the submodule repository ensures that the changes are properly scoped and can be easily shared with the community.
• Flexible testing: This approach allows switching between different versions of the submodule during development and testing, independent of the main repository.

Step-by-Step Guide: Integrating a Modified Submodule (MLPCpp) into SU2

This guide explains how to configure the SU2 build system to use a local version of MLPCpp that contains your modifications. This approach allows you to test changes in the submodule independently of the version tracked by SU2.

Prerequisites

• A forked and cloned MLPCpp repository with your changes (e.g., at /home/youruser/dev/MLPCpp-modified).
• A local SU2 repository (e.g., at /home/youruser/dev/SU2) with a successful initial build.
• Meson and Ninja installed.

1. Replace the Submodule Reference with a Local Path

By default, SU2’s subprojects/MLPCpp points to a specific commit in the official MLPCpp repository. To override this:

1. Backup the current MLPCpp submodule (optional but recommended):

cd /home/youruser/dev/SU2/subprojects
mv MLPCpp MLPCpp_backup

1. Create a symbolic link to your modified MLPCpp:

ln -s /home/youruser/dev/MLPCpp-modified MLPCpp

Note on Symbolic Links:
A symbolic link (symlink) is a file that acts as a reference to another file or directory. In this case, the symlink MLPCpp points to your local modified repository. This ensures that changes in /home/youruser/dev/MLPCpp-modified are reflected in SU2’s build without altering the original submodule structure.

2. Reconfigure and Rebuild SU2 with Meson

1. Navigate to the SU2 build directory (use the same directory as your initial build or create a new one):

cd /home/youruser/dev/SU2/build

1. Reconfigure the build (this picks up the modified submodule).
   Correction: Meson requires the build directory to be separate from the source directory. Run:

meson setup --reconfigure ~/SU2

This tells Meson:

• --reconfigure → Reconfigure an existing build.
• ~/SU2 → Use this as the source directory (SU2’s codebase).
• . → Use the current directory (which should be your separate build directory) as the build output directory.

1. Build SU2 with the modified submodule:

./ninja -C build install

3. Testing Your Changes

Once built, use your modified SU2 executable (from build/bin/SU2_CFD) with configurations that invoke MLPCpp features. This ensures that SU2 is running with your modified submodule code.

Why This Approach Works

• Safe Testing: You avoid accidental changes to the main SU2 repository.
• Submodule Independence: Your local version of MLPCpp can evolve separately from SU2’s tracked version.
• Reproducibility: You can easily switch between your modified MLPCpp and the official version by replacing the symlink.

Conclusion

When contributing to a submodule within a larger open-source project, such as MLPCpp within SU2, the recommended workflow is to fork and modify the submodule directly. Use symbolic links or build system overrides to integrate and test these changes with the main project. This approach ensures a clean, maintainable development workflow and facilitates contribution back to the original project.

Core Proxy Configuration Methods

1. Environment Variables in /etc/environment

The /etc/environment file is one of the most fundamental ways to set system-wide proxy settings. This file is read at boot time and affects all users on the system. When setting up your proxy, you’ll need to replace the port number (3128 in this example) with the specific port your proxy server uses.

http_proxy="http://proxy.example.com:3128"
https_proxy="http://proxy.example.com:3128"
ftp_proxy="http://proxy.example.com:3128"
no_proxy="localhost,127.0.0.1,::1"

HTTP_PROXY="http://proxy.example.com:3128"
HTTPS_PROXY="http://proxy.example.com:3128"
FTP_PROXY="http://proxy.example.com:3128"
NO_PROXY="localhost,127.0.0.1,::1"

The no_proxy variable is particularly important as it tells your system which addresses should bypass the proxy server. This includes localhost and your local network addresses, ensuring direct communication for internal resources.

Key characteristics:

• System-wide configuration affecting all users
• Loaded very early in the boot process
• Changes require a system reboot or re-login
• Both lowercase and uppercase variables are recommended for maximum compatibility

2. Profile Configuration in /etc/profile.d/

Creating a proxy configuration file in /etc/profile.d/ is another system-wide approach. This method offers better organization and easier maintenance compared to modifying /etc/profile directly.

# /etc/profile.d/proxy.sh
export http_proxy="http://proxy.example.com:3128"
export https_proxy="http://proxy.example.com:3128"
export ftp_proxy="http://proxy.example.com:3128"
export no_proxy="localhost,127.0.0.1,::1"

Key characteristics:

• Affects all users who use a shell
• Takes effect on new shell sessions
• More flexible than /etc/environment as it allows for script logic
• Changes apply after logging out and back in

3. User-Specific Configuration in ~/.bashrc

The ~/.bashrc method provides user-level proxy configuration, perfect when different users need different proxy settings:

# Add to ~/.bashrc
export http_proxy="http://proxy.example.com:3128"
export https_proxy="http://proxy.example.com:3128"
export ftp_proxy="http://proxy.example.com:3128"
export no_proxy="localhost,127.0.0.1,::1"

Key characteristics:

• Affects only the specific user
• Applied only to bash shell sessions
• Changes take effect in new terminal windows
• Ideal for user-specific proxy settings

4. GNOME/Ubuntu Settings GUI

For users who prefer a graphical interface, Ubuntu provides proxy settings through the System Settings application. You can find these settings by:

1. Opening Settings
2. Navigating to Network
3. Selecting Network Proxy
4. Choosing ‘Manual’ from the dropdown menu
5. Entering your proxy information in the provided fields

This method is particularly useful for users who are less comfortable with command-line configuration.

5. Apt Proxy Configuration

Apt has its own proxy configuration in /etc/apt/apt.conf.d/:

# /etc/apt/apt.conf.d/80proxy
Acquire::http::Proxy "http://proxy.example.com:3128";
Acquire::https::Proxy "http://proxy.example.com:3128";

Key characteristics:

• Specific to package management
• System-wide configuration
• Independent of other proxy settings
• Takes effect immediately

Application-Specific Proxy Settings

Different applications may require their own proxy configurations. You can verify your current proxy settings at any time by running:

env | grep -i proxy

wget

• Uses environment variables by default
• Can be configured in ~/.wgetrc:

  use_proxy=yes
  http_proxy=http://proxy.example.com:3128
  https_proxy=http://proxy.example.com:3128
  

curl

• Respects environment variables
• Can use command-line options:

  curl --proxy http://proxy.example.com:3128
  

git

• Configure proxy settings specifically for git:

  git config --global http.proxy http://proxy.example.com:3128
  git config --global https.proxy http://proxy.example.com:3128
  

Order of Precedence

Understanding how different proxy settings interact is crucial. They are typically applied in this order:

1. Command-line arguments (highest precedence)
2. Application-specific configuration
3. User-specific environment variables (~/.bashrc)
4. System-wide environment variables (/etc/environment)
5. Default settings (lowest precedence)

Conclusion

Ubuntu’s flexible proxy configuration system allows for both system-wide and user-specific settings. While this flexibility is powerful, it’s important to understand how different methods interact and choose the appropriate approach for your specific needs. For most users, a combination of /etc/environment for system-wide settings and application-specific configurations will provide the most reliable setup. Remember to always verify your settings using the env | grep -i proxy command after making changes.

Important Note About SSH Sessions and Proxy Settings

When working with remote systems through SSH, you might encounter a situation where proxy settings configured through Ubuntu’s graphical interface aren’t visible in your SSH session. This occurs because SSH sessions create a separate environment that doesn’t automatically inherit settings from the graphical user interface.

Think of this like having two different entrances to a building: the main entrance (graphical login) and a side door (SSH). Settings configured through the GUI are like instructions posted at the main entrance – they won’t be visible if you enter through the side door.

To ensure your proxy settings work consistently across both regular and SSH sessions, use one of these configuration methods on your remote system:

1. Add your proxy settings to /etc/environment:

   http_proxy="http://proxy.example.com:3128"
   https_proxy="http://proxy.example.com:3128"
   

2. Create a file in /etc/profile.d/proxy.sh:

   export http_proxy="http://proxy.example.com:3128"
   export https_proxy="http://proxy.example.com:3128"
   

3. Add the settings to the user’s ~/.bashrc:

   export http_proxy="http://proxy.example.com:3128"
   export https_proxy="http://proxy.example.com:3128"
   

After making these changes, your proxy settings will work consistently regardless of how you access the system. You can verify the settings are active in your SSH session by running:

env | grep -i proxy

This ensures that all applications requiring proxy access will work correctly, whether you’re accessing the system through a graphical session or SSH.

Want to access your remote systems without the hassle of typing passwords? Let’s set it up in three easy steps.

1. Generate Your SSH Key

First, we’ll create your SSH key pair. Open your terminal and run:

ssh-keygen -t rsa

When you run this command:

• It will ask where to save the key (usually ~/.ssh/id_rsa) - just press Enter to accept the default
• It will ask for a passphrase - you can press Enter twice to skip it
• This creates two files: id_rsa (private key) and id_rsa.pub (public key)

2. Copy Your Key to the Remote Server

Now let’s copy your public key to the remote server. Here’s the easiest way:

ssh-copy-id username@remote-server

For example, if your username is john and server is example.com:

ssh-copy-id john@example.com

You’ll need to enter your password one last time for this step.

3. Make Life Even Easier with SSH Config

Create or edit ~/.ssh/config file:

nano ~/.ssh/config

Add your server details like this:

Host myserver
    HostName example.com
    User john
    Port 22

Now instead of typing:

ssh john@example.com

You can simply type:

ssh myserver

And that’s it! You can now log in to your remote server without typing passwords or long server names.

Remember:

• Keep your private key (id_rsa) safe and never share it
• You can use different names in the config file for different servers
• The config file can handle multiple server entries