CFD Framework

A production-grade computational fluid dynamics (CFD) library in C for solving 2D/3D incompressible Navier-Stokes equations.

Features

• 🚀 Multiple Backends: CPU (scalar), SIMD (AVX2/NEON), OpenMP, CUDA
• 🔧 Pluggable Solvers: Explicit Euler, Projection Method (Chorin's algorithm)
• 📊 Linear Solvers: Jacobi, SOR, Red-Black SOR, CG/PCG, BiCGSTAB
• 🎯 Validated: Ghia lid-driven cavity, Taylor-Green vortex benchmarks
• 📈 VTK/CSV Output: Ready for ParaView, VisIt visualization
• ⚡ Performance: SIMD-optimized with runtime CPU detection
• 🌐 3D Support: Full 3D simulations with nz>1, branch-free 2D compatibility

Quick Start

Prerequisites

• CMake 3.10+
• C compiler (GCC, Clang, MSVC)
• CUDA Toolkit (optional, for GPU)

Build & Run

# Build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# Run example
cd build/Release
./minimal_example

# Visualize with ParaView or VisIt
# VTK files are written to output/ directory

Windows Quick Build

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure

Linux/macOS Quick Build

./build.sh build    # Build project
./build.sh test     # Run tests
./build.sh run      # Run examples

Basic Usage

#include "cfd/api/simulation_api.h"
#include "cfd/io/vtk_output.h"

int main(void) {
    // Initialize library
    cfd_status_t status = cfd_init();
    if (status != CFD_SUCCESS) {
        fprintf(stderr, "Init failed: %s\n", cfd_get_last_error());
        return 1;
    }

    // Create 2D simulation (100x50 grid, domain [0,1] x [0,0.5])
    // For 3D: use nz>1 and set z-range, e.g. init_simulation(64, 64, 64, ...)
    simulation_data* sim = init_simulation(100, 50, 1, 0.0, 1.0, 0.0, 0.5, 0.0, 0.0);
    if (!sim) {
        fprintf(stderr, "Failed to create simulation\n");
        return 1;
    }

    // Configure parameters
    sim->params.dt = 0.001;
    sim->params.mu = 0.01;  // Viscosity

    // Run simulation steps
    for (int step = 0; step < 1000; step++) {
        status = run_simulation_step(sim);
        if (status != CFD_SUCCESS) {
            fprintf(stderr, "Step failed: %s\n", cfd_get_last_error());
            break;
        }
    }

    // Export results to VTK
    write_vtk_file("output/result.vtk", sim->field, sim->grid);

    // Cleanup
    free_simulation(sim);
    cfd_cleanup();

    return 0;
}

Available Solvers

Solver	Backend	Description
explicit_euler	Scalar	Basic explicit Euler
explicit_euler_optimized	SIMD	SIMD-optimized Euler (AVX2/NEON)
explicit_euler_omp	OpenMP	Multi-threaded Euler
projection	Scalar	Chorin's projection method
projection_optimized	SIMD	SIMD-optimized projection (AVX2/NEON)
projection_omp	OpenMP	Multi-threaded projection
projection_jacobi_gpu	GPU	CUDA-accelerated projection
rk2	Scalar	2nd-order Runge-Kutta

Project Structure

.
├── lib/                    # CFD Library
│   ├── include/cfd/        # Public headers
│   └── src/                # Implementation
│       ├── core/           # Grid, memory, utilities
│       ├── solvers/        # Navier-Stokes solvers
│       │   ├── cpu/        # Scalar implementations
│       │   ├── simd/       # AVX2/NEON optimized
│       │   ├── omp/        # OpenMP parallelized
│       │   └── gpu/        # CUDA kernels
│       ├── linear/         # Poisson/linear solvers
│       └── api/            # Public API
├── tests/                  # Comprehensive test suite
├── examples/               # Example programs
└── docs/                   # Documentation

Documentation

• Building & Installation - Detailed build instructions
• Architecture - Design principles and patterns
• API Reference - Complete API documentation
• Solvers - Numerical methods and performance
• Examples - Example programs guide
• Validation - Benchmark results

Examples

1. Minimal Example

./build/Release/minimal_example

Simplest possible usage - 50 lines showing library basics.

2. Minimal 3D Example

./build/Release/minimal_example_3d

3D simulation on a 16×16×16 grid — demonstrates 3D API usage.

3. Lid-Driven Cavity

./build/Release/lid_driven_cavity 100

Classic CFD benchmark validated against Ghia et al. (1982).

4. Custom Boundary Conditions

./build/Release/custom_boundary_conditions

Flow around cylinder with complex geometry.

See examples documentation for more details.

Performance

Typical performance (100x50 grid, 50 steps, Release mode):

Solver	Time	Speedup
explicit_euler	2.6ms	1.0x
explicit_euler_optimized	0.9ms	2.9x
projection	19.0ms	1.0x
projection_optimized	5.3ms	3.6x

GPU acceleration shows significant benefits for grids ≥200x200.

Testing

# Run all tests
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure

# Run specific test category
ctest --test-dir build -C Debug -R "Validation" --output-on-failure

60+ tests covering:

• Unit tests for core functionality
• Solver accuracy and convergence
• Physics validation benchmarks
• Cross-architecture consistency

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please see development guidelines and ROADMAP for current priorities.

Citation

If you use this library in your research, please cite:

@software{cfd_framework,
  title = {CFD Framework: A Modular C Library for Computational Fluid Dynamics},
  author = {Shaia Halevy},
  year = {2025},
  url = {https://github.com/shaia/CFD}
}

Support

For questions, bug reports, or feature requests, please:

• Check existing documentation
• Review examples
• See architecture guide for design details

Acknowledgments

• Validated against Ghia et al. (1982) lid-driven cavity benchmark
• Unity testing framework
• Inspiration from Ferziger & Peric's "Computational Methods for Fluid Dynamics"