Skip to content

Getting Started

shaia edited this page Oct 5, 2026 · 3 revisions

Getting Started

This guide will help you build the CFD library and run your first simulation.

Prerequisites

  • CMake 3.10 or higher
  • C Compiler: GCC, Clang, or MSVC
  • Build system: Make, Ninja, or Visual Studio
  • Optional: CUDA Toolkit (for GPU acceleration)
  • Optional: OpenMP (for the *_omp solvers; usually bundled with the compiler)
  • Optional: ParaView or VisIt (for viewing VTK output)
  • Optional: Python 3 with numpy (only for the .cfdnn model exporter in tools/cfdnn)

Building

Quick Build with Script

# Clone the repository
git clone https://github.com/shaia/CFD.git
cd CFD

# Build (CPU only, Debug by default; CMAKE_BUILD_TYPE=Release for an optimized build)
./build.sh build

# Build with tests
./build.sh build-tests

# Run the fast test subset ("./build.sh test all" adds the long validation tests)
./build.sh test

Manual Build

mkdir build && cd build
cmake ..
cmake --build . --config Release

A plain cmake configure builds both the examples and the tests. ./build.sh build turns the tests off.

Build with GPU Support

cmake -DCFD_ENABLE_CUDA=ON -B build
cmake --build build --config Release

Build Options

Option Default Description
CFD_ENABLE_CUDA OFF Enable CUDA GPU acceleration
CFD_ENABLE_AVX2 OFF Compile the AVX2 kernels; required by the *_optimized Navier-Stokes solvers
BUILD_EXAMPLES ON Build example programs
BUILD_TESTS ON Build test executables
BUILD_DOCS OFF Build Doxygen documentation
CFD_CUDA_ARCHITECTURES 75;80;86;89;90 Target GPU architectures
CAVITY_FULL_VALIDATION OFF Enable the expensive 129x129 cavity validation test

Running Examples

After building, examples are in the build/ directory:

# On Windows
cd build/Release
./minimal_example.exe
./basic_simulation.exe

# On Linux/macOS
cd build
./minimal_example
./basic_simulation

Output files are created under ../../artifacts/output/, resolved against the directory you run from (running from build/Release writes to <repo>/artifacts/output/). Each run gets its own <prefix>_<nx>x<ny>_<timestamp>/ directory; see Output System.

Your First Simulation

Create a file my_simulation.c:

#include "cfd/api/simulation_api.h"
#include <stdio.h>

int main() {
    // Create a 50x50 grid on a 1x1 domain (nz=1 for 2D)
    simulation_data* sim = init_simulation(50, 50, 1, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0);

    if (!sim) {
        printf("Failed to create simulation\n");
        return 1;
    }

    // Configure output
    simulation_set_run_prefix(sim, "my_first_sim");
    simulation_register_output(sim, OUTPUT_VELOCITY_MAGNITUDE, 5, "velocity");
    simulation_register_output(sim, OUTPUT_CSV_TIMESERIES, 1, "timeseries");

    printf("Running simulation...\n");

    // Run 50 time steps
    for (int step = 0; step < 50; step++) {
        run_simulation_step(sim);
        simulation_write_outputs(sim, step);

        if (step % 10 == 0) {
            printf("Step %d complete\n", step);
        }
    }

    printf("Simulation complete!\n");
    printf("Output files in: ../../artifacts/output/my_first_sim_*/\n");

    free_simulation(sim);
    return 0;
}

Add to CMakeLists.txt:

add_executable(my_simulation my_simulation.c)
target_link_libraries(my_simulation PRIVATE CFD::Library)

Build and run:

cmake --build build
./build/my_simulation

Visualizing Results

With ParaView (Recommended)

  1. Open ParaView
  2. File > Open > Select VTK files from output directory
  3. Apply to load
  4. Use "Contour" or "Glyph" filters for visualization

With Python

The repository ships no plotting scripts. Read the VTK and CSV files with your own code; Output System has vtk and pandas examples.

pip install matplotlib numpy pandas

Next Steps

Clone this wiki locally