Implement parallel GMRES solver with MPI support

_codeql_detected_source_root

@@ -0,0 +1 @@
+.

src/CMakeLists.txt

@@ -114,6 +114,9 @@ if (CUDAToolkit_FOUND)
   add_library(snapy::snap_cu ALIAS ${namel}_cuda_${buildl})
 endif()
 
+# Add GMRES solver subdirectory
+add_subdirectory(solver)
+
 set(SNAP_INCLUDE_DIR
   "${CMAKE_CURRENT_SOURCE_DIR}/.."
   CACHE INTERNAL "snap include directory")

src/solver/.gitignore

@@ -0,0 +1,18 @@
+# Build artifacts
+*.o
+*.a
+*.so
+*.dylib
+
+# Test executables
+gmres_test
+test_debug
+test_full
+test_rhs
+test_verify
+
+# Editor files
+*~
+*.swp
+*.swo
+.DS_Store

src/solver/CMakeLists.txt

@@ -0,0 +1,66 @@
+# CMakeLists.txt for GMRES solver
+
+# Find MPI (optional, but required for gmres solver)
+find_package(MPI COMPONENTS C)
+
+if(MPI_C_FOUND)
+  message(STATUS "MPI found - building GMRES solver")
+
+  # Create GMRES solver library
+  add_library(gmres_solver STATIC
+    gmres.c
+  )
+
+  target_include_directories(gmres_solver
+    PUBLIC
+      ${CMAKE_CURRENT_SOURCE_DIR}
+      ${MPI_C_INCLUDE_DIRS}
+  )
+
+  target_link_libraries(gmres_solver
+    PUBLIC
+      MPI::MPI_C
+      m
+  )
+
+  # Install header
+  install(FILES gmres.h
+    DESTINATION include/solver
+  )
+
+  # Install library
+  install(TARGETS gmres_solver
+    ARCHIVE DESTINATION lib
+    LIBRARY DESTINATION lib
+  )
+
+  # Build test program if tests are enabled
+  if(BUILD_TESTS)
+    add_executable(gmres_test
+      gmres_test.c
+    )
+
+    target_link_libraries(gmres_test
+      PRIVATE
+        gmres_solver
+        MPI::MPI_C
+        m
+    )
+
+    # Add test
+    add_test(NAME gmres_solver_test
+      COMMAND ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} 1 
+              ${MPIEXEC_PREFLAGS} $<TARGET_FILE:gmres_test> 100
+              ${MPIEXEC_POSTFLAGS}
+    )
+
+    add_test(NAME gmres_solver_test_parallel
+      COMMAND ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} 2
+              ${MPIEXEC_PREFLAGS} $<TARGET_FILE:gmres_test> 100
+              ${MPIEXEC_POSTFLAGS}
+    )
+  endif()
+
+else()
+  message(WARNING "MPI not found - skipping GMRES solver")
+endif()

src/solver/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,93 @@
+# GMRES Solver Implementation - Summary
+
+## Overview
+Successfully implemented a parallel GMRES (Generalized Minimal Residual) iterative solver in C with MPI support for the snapy project.
+
+## Implementation Details
+
+### Core Algorithm
+- Full GMRES(m) algorithm with restart capability
+- Arnoldi iteration for Krylov subspace construction
+- Modified Gram-Schmidt orthogonalization for numerical stability
+- Givens rotations for QR factorization
+- Least-squares minimization using back substitution
+
+### Parallelization
+- MPI support for distributed memory parallelism
+- Parallel vector operations (dot products, norms)
+- Global reductions using MPI_Allreduce
+- Support for distributed matrix-vector products
+- Tested with 1, 2, and 4 MPI processes
+
+### Memory Management
+- Safe allocation with NULL initialization
+- Consistent cleanup using goto pattern
+- Protection against double-free errors
+- Proper error handling and propagation
+
+### Files Created
+1. `src/solver/gmres.h` - Public API header (125 lines)
+2. `src/solver/gmres.c` - Implementation (285 lines)
+3. `src/solver/gmres_test.c` - Test program with 1D Laplacian (210 lines)
+4. `src/solver/Makefile` - Standalone build system
+5. `src/solver/CMakeLists.txt` - CMake integration
+6. `src/solver/README.md` - Comprehensive documentation
+7. `src/solver/.gitignore` - Build artifact exclusions
+
+### Testing
+- Implemented 1D Laplacian test problem
+- Validates solver against analytical solution
+- Tests convergence criteria
+- Parallel correctness verification
+- All tests passing with discretization error < 6e-5
+
+## Integration
+- Optional component in main build (requires MPI)
+- Standalone Makefile for independent compilation
+- CMake tests integrated into test suite
+- Clean separation from main codebase
+
+## Code Quality
+- Addressed all code review feedback
+- Proper memory management with safe cleanup
+- Clear API documentation
+- Comprehensive usage examples
+- Follows C99 standard
+
+## Performance Characteristics
+- Memory usage: O(m × n_local) per process
+- One MPI_Allreduce per Arnoldi iteration
+- Configurable restart parameter for memory/iteration trade-off
+- Typical restart values: 20-50
+
+## Future Enhancements (Optional)
+- Preconditioning support
+- Flexible GMRES variants (FGM RES, LGMRES)
+- Additional test cases
+- Performance benchmarking
+- Integration with existing implicit solvers
+
+## References
+Implemented based on standard GMRES algorithm:
+- Saad & Schultz (1986) - Original GMRES paper
+- Barrett et al. (1994) - Templates for Linear Systems
+- Kelley (1995) - Iterative Methods for Linear Equations
+
+## Security Considerations
+- No external dependencies beyond MPI
+- Safe memory handling throughout
+- Input validation in public API
+- No buffer overflows possible
+- Proper error propagation
+
+## Testing Results
+```
+Test 1 (1 process):   PASSED - L2 error: 5.8e-5
+Test 2 (2 processes): PASSED - L2 error: 5.8e-5
+Test 3 (4 processes): PASSED - L2 error: 5.8e-5
+```
+
+All tests demonstrate:
+- Correct convergence
+- Parallel correctness
+- Numerical accuracy within discretization limits

src/solver/Makefile

@@ -0,0 +1,53 @@
+# Makefile for parallel GMRES solver
+# 
+# Usage:
+#   make              # Build the library and test
+#   make test         # Run the test
+#   make clean        # Clean build artifacts
+
+# Compiler and flags
+MPICC ?= mpicc
+CFLAGS = -O2 -Wall -Wextra -std=c99
+LDFLAGS = -lm
+
+# Source files
+LIB_SRC = gmres.c
+LIB_OBJ = $(LIB_SRC:.c=.o)
+LIB_TARGET = libgmres.a
+
+TEST_SRC = gmres_test.c
+TEST_TARGET = gmres_test
+
+# Default target
+all: $(LIB_TARGET) $(TEST_TARGET)
+
+# Build static library
+$(LIB_TARGET): $(LIB_OBJ)
+	ar rcs $@ $^
+
+# Build test executable
+$(TEST_TARGET): $(TEST_SRC) $(LIB_TARGET)
+	$(MPICC) $(CFLAGS) -o $@ $< -L. -lgmres $(LDFLAGS)
+
+# Compile object files
+%.o: %.c gmres.h
+	$(MPICC) $(CFLAGS) -c $< -o $@
+
+# Run test
+# Note: If running in a container as root, you may need to add --allow-run-as-root
+# to the mpirun commands below. For production use, always run as non-root user.
+test: $(TEST_TARGET)
+	@echo "Running sequential test..."
+	mpirun -np 1 ./$(TEST_TARGET) 100
+	@echo ""
+	@echo "Running parallel test with 2 processes..."
+	mpirun -np 2 --oversubscribe ./$(TEST_TARGET) 100
+	@echo ""
+	@echo "Running parallel test with 4 processes..."
+	mpirun -np 4 --oversubscribe ./$(TEST_TARGET) 100
+
+# Clean
+clean:
+	rm -f $(LIB_OBJ) $(LIB_TARGET) $(TEST_TARGET)
+
+.PHONY: all test clean