Skip to content

README.md

Latest commit

 

History

History
174 lines (127 loc) · 4.37 KB

README.md

File metadata and controls

174 lines (127 loc) · 4.37 KB
Raw

LinAlgLib

LinAlgLib is a C++17 sparse linear algebra library focused on iterative methods, algebraic multigrid (AMG), and CPU/GPU execution backends.

Features

  • Sparse matrix and vector primitives (CSR-based workflows)
  • Iterative solvers
    • Classic: Jacobi, Gauss-Seidel, Symmetric Gauss-Seidel, Richardson, SOR, SSOR
    • Krylov: CG, GMRES, BiCGSTAB
  • AMG components
    • Ruge-Stuben AMG
    • Smoothed Aggregation AMG
    • Unsmoothed Aggregation AMG
  • Preconditioners (Jacobi, ILU/IC variants, and related methods)
  • Optional CUDA backend for device execution
  • Example applications and test clients
  • Doxygen API documentation

Repository Layout

library/
	include/            # Public headers
	src/                # Library implementation
clients/
	examples/           # Example executables
	testing/            # Test executable and test utilities
docs/
	Doxyfile            # Doxygen configuration

Prerequisites

  • CMake 3.25+
  • C++17 compiler
    • MSVC (Windows)
    • GCC/Clang (Linux/macOS)
  • Optional:
    • CUDA Toolkit (for device backend)
    • OpenMP
    • MPI

Notes:

  • The project auto-fetches some dependencies (for example GoogleTest and yaml-cpp in testing).
  • CUDA is enabled by default when available (ENABLE_CUDA=ON).

Build

Configure and build (Debug)

cd LinAlgLib
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug

Configure and build (Release)

cd LinAlgLib
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Build with CUDA disabled

cd LinAlgLib
cmake -S . -B build -DENABLE_CUDA=OFF
cmake --build build --config Release

Run Examples

Example targets are generated from files in clients/examples. Common targets include:

  • jacobi_example
  • gmres_example
  • pcg_example
  • rsamg_example
  • saamg_example
  • uaamg_example

Build an example target:

cmake --build build --config Release --target jacobi_example

Run (Windows example path):

build/clients/examples/Release/jacobi_example.exe

Run Tests

The test executable target is test_main under clients/testing.

Build tests:

cmake --build build --config Debug --target test_main

Run (Windows example path):

build/clients/testing/Debug/test_main.exe

Generate Documentation

cd LinAlgLib
doxygen docs/Doxyfile

Generated HTML docs are typically written to docs/html.

Formatting

Example formatting command:

clang-format.exe -i --style microsoft library/src/iterative_solvers/amg/*.cpp

Troubleshooting

  • CMake configure fails:
    • Delete build/ and reconfigure from scratch.
    • Verify CMake version and compiler are available in PATH.
  • CUDA expected but not enabled:
    • Confirm CUDA Toolkit is installed and visible to CMake.
    • Check configure output for CMAKE_CUDA_COMPILER detection messages.
  • Host/device mismatch runtime errors:
    • Ensure all solver inputs participating in a backend dispatch are on the same backend.
  • Linker errors for templated CUDA helpers:
    • Verify required explicit template instantiations exist in CUDA translation units.

Continuous Integration

This repository uses GitHub Actions to validate the codebase. The CI workflow is defined in .github/workflows/ci.yml and includes the following jobs:

  • build — builds the library and test suite on both ubuntu-latest and windows-latest in Debug and Release.
  • build_in_distros — builds the project inside container images for multiple Linux distros (ubuntu:22.04, debian:12, rockylinux:8).
  • docs — installs Doxygen and Graphviz, generates documentation with doxygen docs/Doxyfile, and validates the generated HTML.

The workflow is triggered on:

  • push to main and master
  • pull_request targeting main and master
  • manual runs via the Actions UI (workflow_dispatch)

Run the workflow manually

If you have repo permissions, trigger the workflow from the GitHub Actions page or use the GitHub CLI:

gh workflow run ci.yml --ref master

Notes

  • The CI uses a modern CMake release on Linux so the project can build with CMake 3.25+.
  • CUDA builds and runtime GPU tests are not supported on GitHub-hosted runners because they do not expose NVIDIA GPUs. For CUDA execution, use a self-hosted GPU runner or local testing environment.

License

This project is licensed under the MIT License. See LICENSE for details.