### Build and Install Single-Precision Example Executable with CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Creates a single-precision example executable (psdrive4) from source files, links required libraries, and installs it to the example directory. This pattern is repeated for multiple single-precision variants including 2D and 3D matrix solvers.

```cmake
set(SEXM4 psdrive4.c screate_matrix.c)
add_executable(psdrive4 ${SEXM4})
target_link_libraries(psdrive4 ${all_link_libs})
install(TARGETS psdrive4 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Install pzdrive_spawn Executable

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

This CMake command installs the pzdrive_spawn target, specifically its runtime components, to a designated directory. The executable will be placed in the "EXAMPLE" subdirectory within the INSTALL_LIB_DIR.

```cmake
install(TARGETS pzdrive_spawn RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Configure make.inc for System Setup

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

This section explains the manual installation process using the 'make.inc' file. This file contains machine-specific settings and is essential for building SuperLU_DIST. Sample 'make.inc' files are provided in the MAKE_INC/ directory for different platforms. Users should copy the appropriate sample file to 'make.inc' and modify it as needed.

```bash
cp MAKE_INC/make.xt5  make.inc

```

--------------------------------

### Build Double Precision Examples (CMake)

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Configures and builds double precision executables for SuperLU Dist examples. This section defines various executables (e.g., pddrive, pddrive3d) using C source files and links them against the SuperLU libraries. It also installs these executables to the example directory.

```cmake
if(enable_double)
  set(DEXM pddrive.c dcreate_matrix.c)
  add_executable(pddrive ${DEXM})
  target_link_libraries(pddrive ${all_link_libs})
  add_superlu_dist_example(pddrive big.rua 2 2)
  install(TARGETS pddrive RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM1 pddrive1.c dcreate_matrix.c)
  add_executable(pddrive1 ${DEXM1})
  target_link_libraries(pddrive1 ${all_link_libs})
  add_superlu_dist_example(pddrive1 big.rua 2 2)
  install(TARGETS pddrive1 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM2 pddrive2.c dcreate_matrix.c dcreate_matrix_perturbed.c)
  add_executable(pddrive2 ${DEXM2})
  target_link_libraries(pddrive2 ${all_link_libs})
  add_superlu_dist_example(pddrive2 big.rua 2 2)
  install(TARGETS pddrive2 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM3 pddrive3.c dcreate_matrix.c)
  add_executable(pddrive3 ${DEXM3})
  target_link_libraries(pddrive3 ${all_link_libs})
  add_superlu_dist_example(pddrive3 big.rua 2 2)
  install(TARGETS pddrive3 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM4 pddrive4.c dcreate_matrix.c)
  add_executable(pddrive4 ${DEXM4})
  target_link_libraries(pddrive4 ${all_link_libs})
  install(TARGETS pddrive4 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  

  set(DEXM3D pddrive3d.c dcreate_matrix.c dcreate_matrix3d.c)
  add_executable(pddrive3d ${DEXM3D})
  target_link_libraries(pddrive3d ${all_link_libs})
  install(TARGETS pddrive3d RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  

  set(DEXM3D pddrive3d_block_diag.c dcreate_matrix.c dcreate_matrix3d.c)
  add_executable(pddrive3d_block_diag ${DEXM3D})
  target_link_libraries(pddrive3d_block_diag ${all_link_libs})
  install(TARGETS pddrive3d_block_diag RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
  
  set(DEXM3D1 pddrive3d1.c dcreate_matrix.c dcreate_matrix3d.c)
  add_executable(pddrive3d1 ${DEXM3D1})
  target_link_libraries(pddrive3d1 ${all_link_libs})
  install(TARGETS pddrive3d1 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM3D2 pddrive3d2.c dcreate_matrix.c dcreate_matrix3d.c)
  add_executable(pddrive3d2 ${DEXM3D2})
  target_link_libraries(pddrive3d2 ${all_link_libs})
  install(TARGETS pddrive3d2 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXM3D3 pddrive3d3.c dcreate_matrix.c dcreate_matrix3d.c)
  add_executable(pddrive3d3 ${DEXM3D3})
  target_link_libraries(pddrive3d3 ${all_link_libs})
  install(TARGETS pddrive3d3 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMG pddrive_ABglobal.c)
  add_executable(pddrive_ABglobal ${DEXMG})
  target_link_libraries(pddrive_ABglobal ${all_link_libs})
  install(TARGETS pddrive_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMG1 pddrive1_ABglobal.c)
  add_executable(pddrive1_ABglobal ${DEXMG1})
  target_link_libraries(pddrive1_ABglobal ${all_link_libs})
  install(TARGETS pddrive1_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMG2 pddrive2_ABglobal.c)
  add_executable(pddrive2_ABglobal ${DEXMG2})
  target_link_libraries(pddrive2_ABglobal ${all_link_libs})
  install(TARGETS pddrive2_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMG3 pddrive3_ABglobal.c)
  add_executable(pddrive3_ABglobal ${DEXMG3})
  target_link_libraries(pddrive3_ABglobal ${all_link_libs})
  install(TARGETS pddrive3_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMG4 pddrive4_ABglobal.c)
  add_executable(pddrive4_ABglobal ${DEXMG4})
  target_link_libraries(pddrive4_ABglobal ${all_link_libs})
  install(TARGETS pddrive4_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(DEXMS pddrive_spawn.c dcreate_matrix.c)
  add_executable(pddrive_spawn ${DEXMS})
  target_link_libraries(pddrive_spawn ${all_link_libs})
  install(TARGETS pddrive_spawn RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  

endif() #### end enable_double
```

--------------------------------

### Build Single Precision Examples (CMake)

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Configures and builds single precision executables for SuperLU Dist examples. Similar to the double precision section, this defines executables (e.g., psdrive, psdrive2) using C source files, links them against SuperLU libraries, and installs them. Some examples are also configured using the `add_superlu_dist_example` function.

```cmake
if(enable_single)
  set(SEXM psdrive.c screate_matrix.c screate_A_x_b.c)
  add_executable(psdrive ${SEXM})
  target_link_libraries(psdrive ${all_link_libs})
  install(TARGETS psdrive RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(SEXM1 psdrive1.c screate_matrix.c)
  add_executable(psdrive1 ${SEXM1})
  target_link_libraries(psdrive1 ${all_link_libs})
  add_superlu_dist_example(psdrive1 big.rua 2 2)
  install(TARGETS psdrive1 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(SEXM2 psdrive2.c screate_matrix.c screate_matrix_perturbed.c)
  add_executable(psdrive2 ${SEXM2})
  target_link_libraries(psdrive2 ${all_link_libs})
  add_superlu_dist_example(psdrive2 big.rua 2 2)
  install(TARGETS psdrive2 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")  
  
  set(SEXM3 psdrive3.c screate_matrix.c)
  add_executable(psdrive3 ${SEXM3})
  target_link_libraries(psdrive3 ${all_link_libs})
  add_superlu_dist_example(psdrive3 big.rua 2 2)
```

--------------------------------

### Build, Install, and Test SuperLU_DIST

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

Standard commands for building, installing, and testing SuperLU_DIST after CMake configuration. 'make' compiles the code, 'make install' installs the libraries, and 'ctest' runs the installed tests. Test outputs are typically found in build/Testing/Temporary/LastTest.log.

```bash
make
make install
ctest

```

--------------------------------

### Build 3D Single-Precision Example with Multiple Source Files in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Demonstrates building a 3D single-precision example executable (psdrive3d) that requires multiple source files including matrix creation utilities. This pattern is used for several 3D variants of the solver.

```cmake
set(SEXM3D psdrive3d.c screate_matrix.c screate_matrix3d.c)
add_executable(psdrive3d ${SEXM3D})
target_link_libraries(psdrive3d ${all_link_libs})
install(TARGETS psdrive3d RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Advanced CMake Installation with Third-Party Libraries

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

Configures a sophisticated SuperLU_DIST build using CMake. This example includes options for ParMETIS, CombBLAS, custom C/C++ compiler flags, shared library settings, and the installation prefix. It assumes third-party libraries like ParMETIS and CombBLAS are already built and configured.

```cmake
cmake .. \
    -DTPL_PARMETIS_INCLUDE_DIRS="${PARMETIS_ROOT}/include;${PARMETIS_ROOT}/metis/include" \
    -DTPL_PARMETIS_LIBRARIES="${PARMETIS_BUILD_DIR}/libparmetis/libparmetis.a;${PARMETIS_BUILD_DIR}/libmetis/libmetis.a" \
    -DTPL_ENABLE_COMBBLASLIB=ON \
    -DTPL_COMBBLAS_INCLUDE_DIRS="${COMBBLAS_ROOT}/_install/include;${COMBBLAS_ROOT}/Applications/BipartiteMatchings" \
    -DTPL_COMBBLAS_LIBRARIES="${COMBBLAS_BUILD_DIR}/libCombBLAS.a" \
    -DCMAKE_C_FLAGS="-std=c99 -g -DPRNTlevel=0 -DDEBUGlevel=0" \
    -DCMAKE_C_COMPILER=mpicc \
    -DCMAKE_CXX_COMPILER=mpicxx \
    -DCMAKE_CXX_FLAGS="-std=c++11" \
    -DTPL_ENABLE_INTERNAL_BLASLIB=OFF \
    -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_INSTALL_PREFIX=.

```

--------------------------------

### Configure Include Directories and Link Libraries in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Sets up the include directory path for SuperLU_Dist source files and defines a list of libraries to be linked to all examples, including the superlu_dist library, BLAS library, and the math library (m) on non-MSVC platforms. This configuration ensures all example targets have access to required headers and dependencies.

```cmake
include_directories(${SuperLU_DIST_SOURCE_DIR}/SRC)

set(all_link_libs superlu_dist ${BLAS_LIB})
if (NOT MSVC)
  list(APPEND all_link_libs m)
endif ()
```

--------------------------------

### Simple CMake Installation with ParMETIS

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

Performs a basic SuperLU_DIST installation using CMake. This command requires ParMETIS and sets the necessary include directories and libraries for it. The installation is performed in a separate build directory.

```bash
mkdir build ; cd build;
cmake .. \
    -DTPL_PARMETIS_INCLUDE_DIRS="${PARMETIS_ROOT}/include;${PARMETIS_ROOT}/metis/include" \
    -DTPL_PARMETIS_LIBRARIES="${PARMETIS_BUILD_DIR}/libparmetis/libparmetis.a;${PARMETIS_BUILD_DIR}/libmetis/libmetis.a"

```

--------------------------------

### Build Complex16-Precision 3D QCD Example Executable in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Creates a C++ based complex16-precision 3D QCD (Quantum Chromodynamics) example executable from a single source file. Demonstrates mixing C++ source files with C linking libraries in the build system.

```cmake
set(ZEXM3DQCD pzdrive3d_qcd.cpp)
add_executable(pzdrive3d_qcd ${ZEXM3DQCD})
target_link_libraries(pzdrive3d_qcd ${all_link_libs})
install(TARGETS pzdrive3d_qcd RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Build Complex16-Precision Example with Test Case Registration in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Creates a complex16-precision example executable (pzdrive1) with test case registration using add_superlu_dist_example macro. This enables automated testing with specified matrix file and process grid dimensions.

```cmake
set(ZEXM1 pzdrive1.c zcreate_matrix.c)
add_executable(pzdrive1 ${ZEXM1})
target_link_libraries(pzdrive1 ${all_link_libs})
add_superlu_dist_example(pzdrive1 cg20.cua 2 2)
install(TARGETS pzdrive1 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Add SuperLU Dist Example (CMake)

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Defines a CMake function to add SuperLU Dist examples. It takes an executable name, matrix file, and process grid dimensions as input. This function is used to set up and run examples for SuperLU Dist.

```cmake
function(add_superlu_dist_example)
  # ... (implementation details omitted for brevity)
endfunction(add_superlu_dist_example)
```

--------------------------------

### Copy Example Matrix Files for SuperLU_DIST

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

This CMake command copies example matrix files (`g20.rua` and `cg20.cua`) from the SuperLU_DIST source directory's example folder to the build directory. This makes these example files available for testing or demonstration purposes within the build environment.

```cmake
file(COPY ${SuperLU_DIST_SOURCE_DIR}/EXAMPLE/g20.rua DESTINATION ${CMAKE_BINARY_DIR}/EXAMPLE)
file(COPY ${SuperLU_DIST_SOURCE_DIR}/EXAMPLE/cg20.cua DESTINATION ${CMAKE_BINARY_DIR}/EXAMPLE)
```

--------------------------------

### Define Default Installation Directories

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Sets default installation directories for include, library, and binary files. It uses GNUInstallDirs on non-Windows systems and defaults to 'include', 'lib', 'bin' on Windows.

```cmake
if(NOT MSVC)
  include(GNUInstallDirs)
  set(default_install_inc_dir ${CMAKE_INSTALL_INCLUDEDIR})
  set(default_install_lib_dir ${CMAKE_INSTALL_LIBDIR})
  set(default_install_bin_dir ${CMAKE_INSTALL_BINDIR})
else() # for Windows
  set(default_install_inc_dir "include")
  set(default_install_lib_dir "lib")
  set(default_install_bin_dir "bin")
endif()

set(INSTALL_INC_DIR "${default_install_inc_dir}" CACHE STRING "The folder where headers will be installed.")
set(INSTALL_LIB_DIR "${default_install_lib_dir}" CACHE STRING "The folder where libraries will be installed.")
set(INSTALL_BIN_DIR "${default_install_bin_dir}" CACHE STRING "The folder where runtime files will be installed.")
```

--------------------------------

### Build Complex16-Precision 3D Solver with Perturbed Matrix in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Constructs a complex16-precision 2D example (pzdrive2) that includes matrix perturbation functionality for numerical testing. Demonstrates handling of additional source files for specialized matrix operations.

```cmake
set(ZEXM2 pzdrive2.c zcreate_matrix.c zcreate_matrix_perturbed.c)
add_executable(pzdrive2 ${ZEXM2})
target_link_libraries(pzdrive2 ${all_link_libs})
add_superlu_dist_example(pzdrive2 cg20.cua 2 2)
install(TARGETS pzdrive2 RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### CMake Build Configuration for SuperLU_DIST with GPU Support

Source: https://context7.com/xiaoyeli/superlu_dist/llms.txt

This bash script configures the build process for SuperLU_DIST using CMake. It sets up paths for external libraries like PARMETIS and COMBBLAS, enables GPU (CUDA) support, and configures OpenMP and Python interfaces. The script then builds and installs the library, runs tests, and provides an example of executing a 3D driver.

```bash
#!/bin/bash

# Set library paths
export PARMETIS_ROOT=/path/to/parmetis
export PARMETIS_BUILD_DIR=${PARMETIS_ROOT}/build
export COMBBLAS_ROOT=/path/to/combblas
export COMBBLAS_BUILD_DIR=${COMBBLAS_ROOT}/_build

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake .. \
    -DCMAKE_C_COMPILER=mpicc \
    -DCMAKE_CXX_COMPILER=mpicxx \
    -DCMAKE_C_FLAGS="-std=c99 -O3 -DPRNTlevel=0 -DDEBUGlevel=0" \
    -DCMAKE_CXX_FLAGS="-std=c++11 -O3" \
    -DCMAKE_INSTALL_PREFIX=./install \
    -DBUILD_SHARED_LIBS=ON \
    -DTPL_ENABLE_PARMETISLIB=ON \
    -DTPL_PARMETIS_INCLUDE_DIRS="${PARMETIS_ROOT}/include;${PARMETIS_ROOT}/metis/include" \
    -DTPL_PARMETIS_LIBRARIES="${PARMETIS_BUILD_DIR}/libparmetis/libparmetis.a;${PARMETIS_BUILD_DIR}/libmetis/libmetis.a" \
    -DTPL_ENABLE_COMBBLASLIB=ON \
    -DTPL_COMBBLAS_INCLUDE_DIRS="${COMBBLAS_ROOT}/_install/include" \
    -DTPL_COMBBLAS_LIBRARIES="${COMBBLAS_BUILD_DIR}/libCombBLAS.a" \
    -DTPL_ENABLE_LAPACKLIB=ON \
    -DTPL_ENABLE_CUDALIB=ON \
    -DCMAKE_CUDA_FLAGS="-arch=sm_80" \
    -DXSDK_INDEX_SIZE=64 \
    -Denable_openmp=ON \
    -Denable_python=ON \
    -DXSDK_ENABLE_Fortran=ON

# Build and install
make -j8
make install

# Run tests
ctest -V

# Example: Run 3D driver with 8 MPI processes (2x2x2 grid)
mpirun -np 8 ./EXAMPLE/pddrive3d -r 2 -c 2 -d 2 ../EXAMPLE/g20.rua

```

--------------------------------

### Add SuperLU_Dist MPI Example Test Function in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Defines a CMake function that creates and registers MPI-based test cases for SuperLU_Dist examples. It accepts a target name, input file, and process grid dimensions (nprow, npcol), then constructs an add_test command that executes the example with MPI using the specified number of processes and command-line arguments for row and column distribution.

```cmake
function(add_superlu_dist_example target input nprow npcol)
    set(EXAMPLE_INPUT "${SuperLU_DIST_SOURCE_DIR}/EXAMPLE/${input}")
    set(EXAMPLE_OUTPUT "${SuperLU_DIST_BINARY_DIR}/EXAMPLE/${target}.out")
    set(EXAMPLE_LOC ${CMAKE_CURRENT_BINARY_DIR})
    MATH( EXPR procs "${nprow}*${npcol}" )
    add_test(${target} ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${procs}
             ${MPIEXEC_PREFLAGS} ${EXAMPLE_LOC}/${target} ${MPIEXEC_POSTFLAGS} -r "${nprow}" -c "${npcol}" "${EXAMPLE_INPUT}")
endfunction()
```

--------------------------------

### Link Libraries for pzdrive_spawn

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

This CMake command links the specified libraries to the pzdrive_spawn target. It ensures that all necessary dependencies defined in all_link_libs are available for the pzdrive_spawn executable.

```cmake
target_link_libraries(pzdrive_spawn ${all_link_libs})
```

--------------------------------

### Set Default Install Prefix

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Ensures a default installation prefix is set if CMAKE_INSTALL_PREFIX is not already defined. This guarantees a predictable installation location.

```cmake
if (NOT CMAKE_INSTALL_PREFIX)
  set(CMAKE_INSTALL_PREFIX /usr/local)
endif()
```

--------------------------------

### Build Complex16-Precision ABGlobal Format Examples in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/EXAMPLE/CMakeLists.txt

Builds a series of complex16-precision solvers using the ABGlobal matrix format for distributed memory processing. Multiple variants handle different solver strategies and configurations.

```cmake
set(ZEXMG pzdrive_ABglobal.c)
add_executable(pzdrive_ABglobal ${ZEXMG})
target_link_libraries(pzdrive_ABglobal ${all_link_libs})
install(TARGETS pzdrive_ABglobal RUNTIME DESTINATION "${INSTALL_LIB_DIR}/EXAMPLE")
```

--------------------------------

### Generate and Install pkg-config File in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Calculates absolute path for pkg-config library directory, configures superlu_dist.pc.in template with @ONLY mode to generate superlu_dist.pc file, and installs it to the pkg-config directory for library discovery.

```CMake
if(IS_ABSOLUTE ${CMAKE_INSTALL_LIBDIR})
  set(pkgconfig_libdir ${CMAKE_INSTALL_LIBDIR})
else()
  set(pkgconfig_libdir ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR})
endif()
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/superlu_dist.pc.in ${CMAKE_CURRENT_BINARY_DIR}/superlu_dist.pc @ONLY)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/superlu_dist.pc
	DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
```

--------------------------------

### CMake: Build Environment Initialization

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Includes necessary CMake modules for testing and language checks. It enforces C++11 as the standard and ensures it's required. It also sets up RPATH settings for installation, including the library directory and usage of link paths.

```cmake
include(CTest)
include(CheckLanguage)

######################################################################
#
# Usual initialization stuff
#
######################################################################
if (NOT CMAKE_CXX_STANDARD)
  set(CMAKE_CXX_STANDARD 11)
  #set(CMAKE_CXX_STANDARD 14)
endif()
set(CMAKE_CXX_STANDARD_REQUIRED ON)

#message("!!!! top: cxx_implicit='${CMAKE_CXX_IMPLICIT_LINK_LIBRARIES}'")

if (XSDK_ENABLE_Fortran)
  enable_language (Fortran)
  set(NOFORTRAN FALSE)
endif()

set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)    ## ????
set(CMAKE_INSTALL_NAME_DIR "${CMAKE_INSTALL_PREFIX}/lib")

#---- For shared library

# use, i.e. don't skip the full RPATH for the build tree
SET(CMAKE_SKIP_BUILD_RPATH  FALSE)

# when building, don't use the install RPATH already
# (but later on when installing)
SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) 

# the RPATH to be used when installing
set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")

# add the automatically determined parts of the RPATH
# which point to directories outside the build tree to the install RPATH
SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
#----
```

--------------------------------

### Build Fortran Example Executables Conditionally in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/FORTRAN/CMakeLists.txt

Conditionally creates Fortran example executable targets (f_pddrive, f_pddrive3d, f_5x5 for double precision and f_pzdrive, f_pzdrive3d for complex16) based on enable_examples, enable_double, and enable_complex16 options. Sets Fortran as the linker language for each executable.

```CMake
if(enable_examples)

if(enable_double)
  set(F_DEXM f_pddrive.F90)
  add_executable(f_pddrive ${F_DEXM})
  target_link_libraries(f_pddrive ${all_link_libs})
  set_target_properties(f_pddrive PROPERTIES LINKER_LANGUAGE Fortran)
  
  set(F_DEXM3D f_pddrive3d.F90)
  add_executable(f_pddrive3d ${F_DEXM3D})
  target_link_libraries(f_pddrive3d ${all_link_libs})
  set_target_properties(f_pddrive3d PROPERTIES LINKER_LANGUAGE Fortran)

  set(F_5x5 f_5x5.F90 sp_ienv.c)
  add_executable(f_5x5 ${F_5x5})
  target_link_libraries(f_5x5 ${all_link_libs})
  set_target_properties(f_5x5 PROPERTIES LINKER_LANGUAGE Fortran)

endif()

if(enable_complex16)
  set(F_ZEXM f_pzdrive.F90)
  add_executable(f_pzdrive ${F_ZEXM})
  target_link_libraries(f_pzdrive ${all_link_libs})
  set_target_properties(f_pzdrive PROPERTIES LINKER_LANGUAGE Fortran)

  set(F_ZEXM3D f_pzdrive3d.F90)
  add_executable(f_pzdrive3d ${F_ZEXM3D})
  target_link_libraries(f_pzdrive3d ${all_link_libs})
  set_target_properties(f_pzdrive3d PROPERTIES LINKER_LANGUAGE Fortran)
endif()

endif()
```

--------------------------------

### Configure MAGMA GPU Library Setup in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Enables MAGMA GPU computing library support when TPL_ENABLE_MAGMALIB option is set. Formats MAGMA library names by replacing semicolon separators with spaces for compiler compatibility. Sets HAVE_MAGMA flag to track MAGMA availability in the build configuration.

```cmake
if(TPL_ENABLE_MAGMALIB)
  set(MAGMA_FOUND TRUE)
endif()

if(MAGMA_FOUND)
  message("-- Using TPL_MAGMA_LIBRARIES='${TPL_MAGMA_LIBRARIES}'")
  set(MAGMA_LIB ${TPL_MAGMA_LIBRARIES})
  string (REPLACE ";" " " MAGMA_LIB_STR "${MAGMA_LIB}")
  set(MAGMA_LIB_EXPORT ${MAGMA_LIB_STR})
  set(HAVE_MAGMA TRUE)
else()
  message("-- Will not link with MAGMA.")
endif()
```

--------------------------------

### CMake: Build Option Configuration

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

Defines various build options for SUPERLU_DIST, including enabling documentation, different precision libraries (single, double, complex16), tests, examples, Fortran support, and Python bindings. It also configures options for integrating external libraries such as BLAS, ParMETIS, COLAMD, LAPACK, CombBLAS, CUDA, NVSHMEM, and MAGMA.

```cmake
# Set up options
option(enable_doc       "Build doxygen documentation" OFF)
option(enable_single    "Enable single precision library" ON)
option(enable_double    "Enable double precision library" ON)
option(enable_complex16 "Enable complex16 precision library" ON)
option(enable_tests  "Build tests" ON)
option(enable_examples  "Build examples" ON)
option(XSDK_ENABLE_Fortran "Enable Fortran" ON)
option(enable_python "Enable Python" ON)

#-- BLAS
option(TPL_ENABLE_INTERNAL_BLASLIB  "Build the CBLAS library" ${enable_blaslib_DEFAULT})
option(TPL_BLAS_LIBRARIES "List of absolute paths to blas libraries [].")
#-- ParMETIS
option(TPL_ENABLE_PARMETISLIB   "Enable the ParMETIS library" ON)
option(TPL_PARMETIS_LIBRARIES "List of absolute paths to ParMETIS link libraries [].")
option(TPL_PARMETIS_INCLUDE_DIRS "List of absolute paths to ParMETIS include directories [].")
#-- COLAMD
option(TPL_ENABLE_COLAMDLIB   "Enable the COLAMD library" OFF)
option(TPL_COLAMD_LIBRARIES "List of absolute paths to COLAMD link libraries [].")
option(TPL_COLAMD_INCLUDE_DIRS "List of absolute paths to COLAMD include directories [].")
#-- LAPACK
option(TPL_ENABLE_LAPACKLIB "Enable LAPACK library" OFF)
option(TPL_LAPACK_LIBRARIES "List of absolute paths to LAPACK libraries [].")
#-- CombBLAS
option(TPL_ENABLE_COMBBLASLIB   "Build the CombBLAS library" OFF)
option(TPL_COMBBLAS_LIBRARIES "List of absolute paths to CombBLAS link libraries [].")
option(TPL_COMBBLAS_INCLUDE_DIRS "List of absolute paths to CombBLAS include directories [].")
#-- CUDA
option(TPL_ENABLE_CUDALIB   "Enable the CUDA libraries" OFF)
option(TPL_ENABLE_HIPLIB   "Enable the HIP libraries" OFF)
#-- NVSHMEM
option(TPL_ENABLE_NVSHMEM   "Enable the NVSHMEM libraries" OFF)
option(TPL_ENABLE_ROCSHMEM   "Enable the ROCSHMEM libraries" OFF)
#-- MAGMA 
option(TPL_ENABLE_MAGMALIB "Enable the MAGMA library" OFF)
```

--------------------------------

### C: Solve 2D Sparse Linear System (pdgssvx)

Source: https://context7.com/xiaoyeli/superlu_dist/llms.txt

Solves a sparse linear system Ax=b using a 2D process grid distribution. It handles matrix setup, factorization with parallel symbolic factorization, and solution. Requires MPI and SuperLU-dist headers.

```c
#include "superlu_ddefs.h"

int main(int argc, char *argv[]) {
    superlu_dist_options_t options;
    SuperLUStat_t stat;
    SuperMatrix A;
    dScalePermstruct_t ScalePermstruct;
    dLUstruct_t LUstruct;
    dSOLVEstruct_t SOLVEstruct;
    gridinfo_t grid;
    double *berr, *b;
    int_t m, n;
    int nprow = 4, npcol = 4;  // 4x4 = 16 processes
    int nrhs = 1, ldb, ldx;
    int info;

    MPI_Init(&argc, &argv);

    // Initialize 2D process grid
    superlu_gridinit(MPI_COMM_WORLD, nprow, npcol, &grid);

    if (grid.iam < nprow * npcol) {
        // Set up matrix and right-hand side
        dcreate_matrix_postfix(&A, nrhs, &b, &ldb,
                               &xtrue, &ldx, "g20.rua", &grid);

        // Configure options for factorization
        set_default_options_dist(&options);
        options.ParSymbFact = YES;  // Parallel symbolic factorization
        options.ColPerm = PARMETIS;
        options.RowPerm = LargeDiag_MC64;

        m = A.nrow;
        n = A.ncol;

        // Initialize structures
        dScalePermstructInit(m, n, &ScalePermstruct);
        dLUstructInit(n, &LUstruct);
        PStatInit(&stat);
        berr = doubleMalloc_dist(nrhs);

        // Solve
        pdgssvx(&options, &A, &ScalePermstruct, b, ldb, nrhs, 
                &grid, &LUstruct, &SOLVEstruct, berr, &stat, &info);

        if (info == 0 && grid.iam == 0) {
            printf("Solution backward error: %e\n", berr[0]);
        }

        // Cleanup
        PStatFree(&stat);
        Destroy_CompRowLoc_Matrix_dist(&A);
        dScalePermstructFree(&ScalePermstruct);
        dDestroy_LU(n, &grid, &LUstruct);
        dLUstructFree(&LUstruct);
        dSolveFinalize(&options, &SOLVEstruct);
        SUPERLU_FREE(berr);
        SUPERLU_FREE(b);
    }

    superlu_gridexit(&grid);
    MPI_Finalize();
    return 0;
}

```

--------------------------------

### Configure SuperLU Dist Runtime with Environment Variables (Bash)

Source: https://context7.com/xiaoyeli/superlu_dist/llms.txt

Control SuperLU Dist's runtime behavior and performance tuning using environment variables. This includes enabling GPU acceleration, setting OpenMP threads, adjusting performance parameters like supernode relaxation and fill ratio, and managing GPU buffer sizes. The examples demonstrate how to launch the solver with different configurations and MPI process grids.

```bash
#!/bin/bash

# GPU acceleration control
export SUPERLU_ACC_OFFLOAD=1  # Enable GPU offloading (default: 1)

# OpenMP threading
export OMP_NUM_THREADS=4  # Number of threads per MPI process

# Performance tuning parameters
export NREL=20      # Supernode relaxation parameter
export NSUP=256     # Maximum supernode size (max 512)
export FILL=20      # Estimated fill ratio: nnz(L+U)/nnz(A)
export MAX_BUFFER_SIZE=500000000  # Max GPU buffer size for GEMM

# Run example with 16 MPI processes on 4x4 grid
# Each process uses 4 OpenMP threads
mpiexec -np 16 ./pddrive -r 4 -c 4 matrix.mtx

# Run 3D example with GPU on 4x4x2 grid (32 processes)
export SUPERLU_ACC_OFFLOAD=1
mpiexec -np 32 ./pddrive3d -r 4 -c 4 -d 2 large_matrix.mtx

# Run with iterative refinement and parallel symbolic factorization
mpiexec -np 16 ./pddrive -r 4 -c 4 -i 1 -p 1 -q 5 -s 1 matrix.rua
# Options: -i 1 (iterative refinement)
#          -p 1 (row permutation LargeDiag_MC64)
#          -q 5 (column permutation PARMETIS)
#          -s 1 (parallel symbolic factorization)

```

--------------------------------

### Install SuperLU_DIST Python library and scripts

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/PYTHON/CMakeLists.txt

Configures installation rules for the compiled Python library and multiple Python script files to the installation library directory. Supports installation to both the main library directory and a dedicated PYTHON subdirectory for organization.

```cmake
install(TARGETS superlu_dist_python DESTINATION "${INSTALL_LIB_DIR}")
install(TARGETS superlu_dist_python DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
install(FILES pddrive.py DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
install(FILES pdbridge.py DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
install(FILES pddrive_worker.py DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
install(FILES pddrive_master.py DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
install(FILES GP_demo.py DESTINATION "${INSTALL_LIB_DIR}/PYTHON")
```

--------------------------------

### Initialize SuperLU Distributed Solver

Source: https://context7.com/xiaoyeli/superlu_dist/llms.txt

Loads the SuperLU Distributed library and configures solver options via command-line arguments. It then initializes the distributed solver, passing matrix data and configuration to the `pdbridge_init` function. Dependencies include `ctypes` for interfacing with the C library.

```python
# Load SuperLU library
sp = pdbridge.load_library(INT64)

# Setup command-line arguments for solver options
argv = ['python']
argv.extend(['-r', '2'])  # 2 process rows
argv.extend(['-c', '2'])  # 2 process columns
argv.extend(['-p', '1'])  # Row permutation: LargeDiag_MC64
argv.extend(['-q', '2'])  # Column permutation: PARMETIS
argv.extend(['-i', '1'])  # Iterative refinement: YES

argc = len(argv)
argv_bytes = [arg.encode('utf-8') for arg in argv]
argv_ctypes = (ctypes.c_char_p * (argc + 1))(*argv_bytes, None)

# Initialize solver
pyobj = ctypes.c_void_p()
sp.pdbridge_init(
    0,  # algo3d: 0 for 2D, 1 for 3D
    n, n, nnz,
    rowind.ctypes.data_as(ctypes.POINTER(ctypes.c_int)),
    colptr.ctypes.data_as(ctypes.POINTER(ctypes.c_int)),
    nzval.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
    ctypes.byref(pyobj),
    argc, argv_ctypes
)

```

--------------------------------

### Configure Fortran Library Dependencies and Installation in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/FORTRAN/CMakeLists.txt

Sets up dependencies on config_f target for Fortran preprocessing, configures installation destinations for libraries and header files including Fortran module files (.mod), and installs both shared and static library variants.

```CMake
add_dependencies(superlu_dist_fortran config_f)
if(BUILD_STATIC_LIBS)
  add_dependencies(superlu_dist_fortran-static config_f)
  add_dependencies(superlu_dist_fortran-static superlu_dist_fortran)
endif()

install(TARGETS superlu_dist_fortran
    RUNTIME DESTINATION "${INSTALL_BIN_DIR}"
    LIBRARY DESTINATION "${INSTALL_LIB_DIR}"
    ARCHIVE DESTINATION "${INSTALL_LIB_DIR}"
)
if (BUILD_STATIC_LIBS)
  install(TARGETS superlu_dist_fortran-static
      RUNTIME DESTINATION "${INSTALL_BIN_DIR}"
      LIBRARY DESTINATION "${INSTALL_LIB_DIR}"
      ARCHIVE DESTINATION "${INSTALL_LIB_DIR}"
  )
endif()

install(FILES superlu_dist_config.fh 
  ${CMAKE_CURRENT_BINARY_DIR}/superlu_mod.mod 
  ${CMAKE_CURRENT_BINARY_DIR}/superlupara_mod.mod
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
  )
```

--------------------------------

### 3D Parallel Sparse Linear Solver with pdgssvx3d in C

Source: https://context7.com/xiaoyeli/superlu_dist/llms.txt

Demonstrates the primary API for solving sparse linear systems using 3D process grids with communication-avoiding algorithms. This example initializes a 2x2x2 process grid, reads a matrix from file, configures solver options including row/column permutations and iterative refinement, performs the LU factorization and solve, and outputs error bounds and statistics. Requires MPI with thread support and proper memory management for large-scale distributed computation.

```C
#include "superlu_ddefs.h"
#include <mpi.h>

int main(int argc, char *argv[]) {
    superlu_dist_options_t options;
    SuperLUStat_t stat;
    SuperMatrix A;
    dScalePermstruct_t ScalePermstruct;
    dLUstruct_t LUstruct;
    dSOLVEstruct_t SOLVEstruct;
    gridinfo3d_t grid;
    double *berr, *b, *xtrue;
    int_t m, n, nnz;
    int nprow = 2, npcol = 2, npdep = 2;  // 2x2x2 = 8 processes
    int nrhs = 1;
    int iam, info;

    // Initialize MPI with thread support
    int provided;
    MPI_Init_thread(&argc, &argv, MPI_THREAD_MULTIPLE, &provided);

    // Initialize 3D process grid
    superlu_gridinit3d(MPI_COMM_WORLD, nprow, npcol, npdep, &grid);

    // Read matrix from file and distribute to process grid
    dcreate_matrix(&A, nrhs, &b, &ldb, &xtrue, &ldx,
                   "matrix.dat", &grid.grid2d);

    // Set default solver options
    set_default_options_dist(&options);
    options.Fact = DOFACT;  // Factorization from scratch
    options.RowPerm = LargeDiag_MC64;  // Row permutation for stability
    options.ColPerm = PARMETIS;  // Parallel column ordering
    options.IterRefine = DOUBLE;  // Iterative refinement
    options.ReplaceTinyPivot = YES;

    // Initialize data structures
    m = A.nrow;
    n = A.ncol;
    dScalePermstructInit(m, n, &ScalePermstruct);
    dLUstructInit(n, &LUstruct);
    PStatInit(&stat);

    // Allocate error bound array
    if (!(berr = doubleMalloc_dist(nrhs)))
        ABORT("Malloc fails for berr[].");

    // Solve the system: A*X = B
    pdgssvx3d(&options, &A, &ScalePermstruct, b, ldb, nrhs,
              &grid, &LUstruct, &SOLVEstruct, berr, &stat, &info);

    if (info == 0) {
        if (grid.iam == 0) {
            printf("Backward error: %e\n", berr[0]);
            printf("Solution computed successfully\n");
        }
    } else {
        printf("ERROR: pdgssvx3d returned info=%d\n", info);
    }

    // Print statistics
    PStatPrint(&options, &stat, &grid.grid2d);

    // Clean up
    PStatFree(&stat);
    Destroy_CompRowLoc_Matrix_dist(&A);
    dScalePermstructFree(&ScalePermstruct);
    dDestroy_LU(n, &grid.grid2d, &LUstruct);
    dLUstructFree(&LUstruct);
    dSolveFinalize(&options, &SOLVEstruct);
    SUPERLU_FREE(berr);
    SUPERLU_FREE(b);
    SUPERLU_FREE(xtrue);

    superlu_gridexit3d(&grid);
    MPI_Finalize();
    return 0;
}
```

--------------------------------

### Enable GPU Acceleration with CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

These CMake options enable GPU acceleration for SuperLU_DIST. Use TPL_ENABLE_CUDALIB for NVIDIA GPUs with CUDA, and TPL_ENABLE_HIPLIB for AMD GPUs with HIP. Ensure the respective GPU libraries are installed before configuring.

```cmake
-DTPL_ENABLE_CUDALIB=TRUE

```

```cmake
-DTPL_ENABLE_HIPLIB=TRUE

```

--------------------------------

### Configure MPIEXEC_EXECUTABLE for ctest

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

This CMake option allows specifying the MPI execution command, which is necessary for parallel testing with 'ctest' if your MPI environment differs from the default (e.g., not MPICH/mpiexec). This example shows how to set it for 'srun' on Cori.

```cmake
-DMPIEXEC_EXECUTABLE=/usr/bin/srun

```

--------------------------------

### Enable and Configure HIP Libraries in CMake

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/CMakeLists.txt

This part of the configuration enables HIP (Heterogeneous-compute Interface for Portability) support. It finds the HIP package and related libraries like hipblas, rocsolver, and rocblas. It then constructs a string of HIP library paths and sets flags for HIP compilation, including PIC for shared libraries.

```cmake
if (TPL_ENABLE_HIPLIB)   ## want to use hip
  find_package(HIP MODULE)
  if(HIP_FOUND)
    message("-- Enabled support for HIP.")
    find_package(hipblas REQUIRED)
    find_package(rocsolver REQUIRED)
    find_package(rocblas REQUIRED)
    set(HIP_LIB roc::hipblas roc::rocblas roc::rocsolver)
    message("HIP_LIB ${HIP_LIB}")

    set(HIP_LIB_EXPORT "") 
    foreach(HIP_LIB_TARGET ${HIP_LIB})
      get_property(HIP_LIB_IMPORTED_CONFIGS TARGET ${HIP_LIB_TARGET} PROPERTY IMPORTED_CONFIGURATIONS)
      foreach(RELTYPE RELEASE RELWITHDEBINFO DEBUG)
        list(FIND HIP_LIB_IMPORTED_CONFIGS ${RELTYPE} HIP_IMPORTED_CONFIG)
        if(${HIP_IMPORTED_CONFIG} GREATER_EQUAL "0")
          list(GET HIP_LIB_IMPORTED_CONFIGS ${HIP_IMPORTED_CONFIG} HIP_LIB_IMPORTED_CONFIG)
          break()
        endif()
      endforeach()
      get_property(HIP_LIB_STR TARGET ${HIP_LIB_TARGET} PROPERTY IMPORTED_LOCATION_${HIP_LIB_IMPORTED_CONFIG})
      message("HIP_LIB_STR ${HIP_LIB_STR}")
      set(HIP_LIB_EXPORT ${HIP_LIB_EXPORT} ${HIP_LIB_STR}) 
      message("HIP_LIB_EXPORT ${HIP_LIB_EXPORT}")
    endforeach()
    string (REPLACE ";" " " HIP_LIB_EXPORT "${HIP_LIB_EXPORT}")
    message("HIP_LIB_EXPORT ${HIP_LIB_EXPORT}")
    set(HAVE_HIP TRUE)
    if (BUILD_SHARED_LIBS)
    set(HIP_HIPCC_FLAGS "${HIP_HIPCC_FLAGS} -fPIC")
    endif()

  else()
    message("-- HIP libraries not found.")
  endif()
endif()
```

--------------------------------

### CMake: Create Symbolic Link for METIS

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/PATCH/parmetis/CMakeLists.txt

Creates a symbolic link named 'metis' pointing to the specified METIS_PATH. This simplifies including header files from 'metis/libmetis/' regardless of the actual location of the METIS installation.

```cmake
execute_process(COMMAND ${CMAKE_COMMAND} -E create_symlink ${METIS_PATH} metis)
```

--------------------------------

### Enable OpenMP and CUDA for SuperLU_DIST

Source: https://github.com/xiaoyeli/superlu_dist/blob/master/README.md

Details the steps for enabling OpenMP parallelism and NVIDIA GPU support in SuperLU_DIST. OpenMP requires linking with an OpenMP library and setting `OMP_NUM_THREADS`. CUDA requires specifying include and library paths for CUDA in `make.inc`, including `cublas` and `cudart`.

```bash
export OMP_NUM_THREADS=<##>
```

```makefile
HAVE_CUDA=TRUE
INCS += -I<CUDA directory>/include
LIBS += -L<CUDA directory>/lib64 -lcublas -lcudart
```